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About This Manual 


Preface 


Read This First 


The TMS320C3x/C4x Assembly Language Tools User’s Guide tells you how 
to use these assembly language tools: 


_j Assembler 

_) Archiver 

_j Linker 

(J) Hex conversion utility 


Before you can use this book, you should read the TMS320C3x/C4x Code 
Generation Tools Getting Started Guide to install the assembly language 
tools. 


How to Use This Manual 


The goal of this book is to help you learn how to use the Texas Instruments 
assembly language tools specifically designed for the TMS320C38x/C4x 
floating-point DSPs. This book is divided into four distinct parts: 


(J PartI: Introductory Information gives you an overview of the assembly 
language development tools and also discusses common object file 
format (COFF) which helps you to use the TMS320C3x and TMS320C4x 
tools more efficiently. Read Chapter 2 before using the assembler and 
linker. 


_) Part Il: Assembler Description contains detailed information about 
using the assembler. This section explains how to invoke the assembler 
and discusses source statement format, valid constants and expressions, 
assembler output, and assembler directives. 


(1 Part Ill: Additional Assembly Language Tools describes in detail each 
of the tools provided with the assembler to help you create assembly 
language source files. For example, Chapter 8 explains how to invoke the 
linker, how the linker operates, and how to use linker directives. 
Chapter 10 explains how to use the hex conversion utility. 
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Notational Conventions 


Lj) Part IV: Reference Material provides supplementary information. This 


section contains technical data about the internal format and structure of 
COFF object files. It discusses symbolic debugging directives that the 
TMS320C3x/C4x C compiler uses. Finally, it includes sample linker 
command files, assembler and linker error messages, and a glossary. 


This document uses the following conventions. 


Lj Program listings, program examples, and interactive displays are shown 


inaspecial typeface similar to a typewriter’s. Examples use a bold 
version of the special typeface for emphasis; interactive displays use a 
bold version of the special typeface to distinguish commands that you 
enter from items that the system displays (such as prompts, command 
output, error messages, etc.). 


Here is a sample program listing: 


0011 0005 0001 -field Lye 
0012 0005 0003 -field 3, 4 
0013 0005 0006 .field 6, 3 
0014 0006 .even 


In syntax descriptions, the instruction, command, or directive is in a bold 
typeface font and parameters are in an italic typeface. Portions of a syntax 
that are in bold should be entered as shown; portions of a syntax that are 
in italics describe the type of information that should be entered. Here is 
an example of command line syntax: 


asm30_ filename 


Here asm30 is a command. The command invokes the assembler and 
has one parameter, indicated by filename. When you invoke the 
assembler, you supply the name of the file that the assembler uses as 
input. 


Square brackets ( [ and ] ) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets; you 
don’t enter the brackets themselves. Here’s an example of an instruction 
that has an optional parameter: 


hex30 [-options] filename 


The hex30 command has two parameters. The first parameter, —options, 
is optional. Since options is plural, you may select several options. The 
second parameter, filename, is required. 


Notational Conventions 


Square brackets are also used as part of the pathname specification for 
VMS pathnames; in this case, the brackets are actually part of the 
pathname (they are not optional). 


In assembler syntax statements, column one is reserved for the first 
character of a label or symbol. If the label or symbol is optional, it is usually 
not shown. If it is a required parameter, then it will be shown starting 
against the left margin of the shaded box, as in the example below. No 
instruction, command, directive, or parameter, other than a symbol or 
label, should begin in column one. 


symbol .usect section name”, size in bytes 


The symbol is required for the .usect directive and must begin in column 
one. The section name must be enclosed in quotes, and the section size in 
bytes must be separated from the section name by a comma. 


Braces( {and} ) indicate alist. The symbol | (read as or) separates items 
within the list. Here’s an example of a list: 


{ * | a4 | x } 
This provides three choices: *, *+, or *-. 


Unless the list is enclosed in square brackets, you must choose one item 
from the list. 


Some directives can have a varying number of parameters. For example, 
the .byte directive can have up to 100 parameters. The syntax for this 
directive is: 


-byte value; [, ... , valueéy] 


This syntax shows that .byte must have at least one value parameter, but 
you have the option of supplying additional value parameters, separated 
by commas. 
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Related Documentation From Texas Instruments 


Related Documentation From Texas Instruments 


vi 


The following books describe the TMS320C3x/C4x and related support tools. 
To obtain a copy of any of these Tl documents, call the Texas Instruments 
Literature Response Center at (800) 477-8924. When ordering, please 
identify the book by its title and literature number. 


TMS320C3x/C4x Code Generation Tools Getting Started Guide (literature 
number SPRU119) describes how to install the TMS320C3x/C4x 
assembly language tools and the C compiler. Installation instructions are 
included for MS—DOS™, Windows 3.x, Windows NT, Windows 95, 
SunOS™, Solaris, and HP—UX™ systems. 


TMS320C3x/C4x Optimizing C Compiler User’s Guide (literature number 
SPRU034) describes the TMS320 floating-point C compiler. This C 
compiler accepts ANSI standard C source code and produces TMS320 
assembly language source code for the ‘C3x and ’C4x generations of 
devices. 


TMS320C3x C Source Debugger User’s Guide (literature number 
SPRU053) tells you how to invoke the ’C3x emulator, evaluation module, 
and simulator versions of the C source debugger interface. This book 
discusses various aspects of the debugger interface, including window 
management, command entry, code execution, data management, and 
breakpoints. It also includes a tutorial that introduces basic debugger 
functionality. 


TMS320C4x C Source Debugger User’s Guide (literature number 
SPRU054) tells you how to invoke the ’C4x emulator and simulator 
versions of the C source debugger interface. This book discusses 
various aspects of the debugger interface, including window 
management, command entry, code execution, data management, and 
breakpoints. It also includes a tutorial that introduces basic debugger 
functionality. 


TMS320C3x User’s Guide (literature number SPRU031) describes the 'C3x 
32-bit floating-point microprocessor (developed for digital signal 
processing as well as general applications), its architecture, internal 
register structure, instruction set, pipeline, specifications, and DMA and 
serial port operation. Software and hardware applications are included. 


TMS320C32 Addendum to the TMS320C3x User’s Guide (literature 
number SPRU132) describes the TMS320C32 _ floating-point 
microprocessor (developed for digital signal processing as well as 
general applications). Discusses its architecture, internal register 
structure, specifications, and DMA and serial port operation. Hardware 
applications are also included. 


Related Documentation From Texas Instruments 


TMS320C4x User’s Guide (literature number SPRU063) describes the ’C4x 
32-bit floating-point processor, developed for digital signal processing as 
well as parallel processing applications. Covered are its architecture, 
internal register structure, instruction set, pipeline, specifications, and 
operation of its six DMA channels and six communication ports. 


Parallel Processing with the TMS320C4x (literature number SPRA031) 
describes parallel processing and how the ’C4x can be used in parallel 
processing. Also provides sample parallel processing applications. 


TMS320C4x General-Purpose Applications User’s Guide (literature 
number SPRU159) describes software and hardware applications for 
the ’C4x processor. Also includes development support information, 
parts lists, and XDS510 emulator design considerations. 


TMS320C30 Evaluation Module Technical Reference (literature number 
SPRUO069) describes board-level operation of the TMS320C30 EVM. 


Digital Signal Processing Applications With the TMS320C30 Evaluation 
Module Selected Application Notes (literature number SPRA021) 
contains useful information for people who are preparing and debugging 
code. The book gives additional information about the TMS320C30 
EVM, as well as C coding tips. 


TMS320 DSP Development Support Reference Guide (literature number 
SPRUO011) describes the TMS320 family of digital signal processors and 
the tools that support these devices. Included are code-generation tools 
(compilers, assemblers, linkers, etc.) and system integration and debug 
tools (simulators, emulators, evaluation modules, etc.). Also covered are 
available documentation, seminars, the university program, and factory 
repair and exchange. 


Digital Signal Processing Applications with the TMS320 Family, Volumes 
1, 2, and 3 (literature numbers SPRA012, SPRAO16, SPRAO17) 
Volumes 1 and 2 cover applications using the ‘C10 and ’C20 families of 
fixed-point processors. Volume 3 documents applications using both 
fixed-point processors, as well as the ’C30 floating-point processor. 


TMS320 DSP Designer’s Notebook: Volume 1 (literature number 
SPRT125) presents solutions to common design problems using ’C2x, 
’C8x, ’C4x, ’C5x, and other TI DSPs. 


TMS320 Third-Party Support Reference Guide (literature number 
SPRU052) alphabetically lists over 100 third parties that provide various 
products that serve the family of ’320 digital signal processors. A myriad 
of products and applications are offered—software and hardware 
development tools, speech recognition, image processing, noise 
cancellation, modems, etc. 
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Trademarks 


Trademarks 
HP-UX is a trademark of Hewlett-Packard Company. 
MS-DOS is a registered trademark of Microsoft Corporation. 
PC-DOS is a trademark of International Business Machines Corporation. 
Solaris is a trademark of Sun Microsystems, Inc. 
SunOS is a trademark of Sun Microsystems, Inc. 


UNIX is a registered trademark in the United States and other countries, 
licensed exclusively through X/Open Company Limited. 


XDS is a trademark of Texas Instruments Incorporated. 
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If You Need Assistance 


If You Need Assistance... 


1 World-Wide Web Sites 


TI Online http://www.ti.com 

Semiconductor Product Information Center (PIC) —_http://www.ti.com/sc/docs/pic/home.htm 
DSP Solutions http://www.ti.com/dsps 

320 Hotline On-line ™ http://www.ti.com/sc/docs/dsps/support.htm 


North America, South America, Central America 


Product Information Center (PIC) (972) 644-5580 
TI Literature Response Center U.S.A. (800) 477-8924 
Software Registration/Upgrades (214) 638-0333 Fax: (214) 638-7742 

U.S.A. Factory Repair/Hardware Upgrades (281) 274-2285 

U.S. Technical Training Organization (972) 644-5580 

DSP Hotline (281) 274-2320 Fax: (281) 274-2324 Email: dsph@ti.com 
DSP Modem BBS (281) 274-2323 

DSP Internet BBS via anonymous ftp to ftp://ftp.ti.com/pub/tms320bbs 


Europe, Middle East, Africa 
European Product Information Center (EPIC) Hotlines: 


Multi-Language Support +383 130701169 Fax: +33 130701032 Email: epic@ti.com 
Deutsch +49 8161 80 33 11 or +33 1 30 70 11 68 
English +33 130 70 11 65 
Francais +33 13070 11 64 
Italiano +33 1 30 70 11 67 
EPIC Modem BBS +33 130 70 11 99 
European Factory Repair +33 4 93 22 25 40 
Europe Customer Training Helpline Fax: +49 81 61 80 40 10 
Asia-Pacific 
Literature Response Center +852 2956 7288 Fax: +852 2 956 2200 
Hong Kong DSP Hotline +852 2956 7268 Fax: +852 2 956 1002 
Korea DSP Hotline +82 2551 2804 Fax: +82 2551 2828 
Korea DSP Modem BBS +82 2551 2914 
Singapore DSP Hotline Fax: +65 390 7179 
Taiwan DSP Hotline +886 23771450 Fax: +886 2 377 2718 
Taiwan DSP Modem BBS +886 2 376 2592 
Taiwan DSP Internet BBS via anonymous ftp to ftp://dsp.ee.tit.edu.tw/pub/T1/ 
Japan 
Product Information Center +0120-81-0026 (in Japan) Fax: +0120-81-0036 (in Japan) 
+03-3457-0972 or (INTL) 813-3457-0972 Fax: +03-3457-1259 or (INTL) 813-3457-1259 
DSP Hotline +03-3769-8735 or (INTL) 813-3769-8735 Fax: +03-3457-7071 or (INTL) 813-3457-7071 
DSP BBS via Nifty-Serve Type “Go TIASP” 


Documentation 
When making suggestions or reporting errors in documentation, please include the following information that is on the title 
page: the full title of the book, the publication date, and the literature number. 
Mail: Texas Instruments Incorporated Email: comments@books.sc.ti.com 
Technical Documentation Services, MS 702 
P.O. Box 1443 
Houston, Texas 77251-1443 


Note: When calling a Literature Response Center to order documentation, please specify the literature number of the 
book. 
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Discusses the basic COFF concept of sections and how they can help you use the assembler 
and linker more efficiently. Common Object File Format, or COFF, is the object file format used 
by the TMS320 family floating-point tools. Read Chapter 2 before using the assembler and 
linker. 
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Tells you how to invoke the assembler and discusses source statement format, valid constants 
and expressions, and assembler output. 


xii 


3.1 
3.2 
3.3 
3.4 
3.5 


3.6 


3.7 


3.8 
3.9 


3.10 


3.11 
3.12 
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4 Assembler Directives ..........00 ccc eee eee eee eee e eee eee eeen eens 4-1] 
Describes the directives according to function, and lists the directives in alphabetical order. 
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Summarizes the TMS320C3x and TMS320C4x instruction sets alphabetically and according 
to function, with information on addressing modes, optional syntaxes, condition codes and 
flags, abbreviations and symbols. 
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5.3 Instruction Set Summary Table .......... 2.00.0 cece cece ence cence ence eens 
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Describes an easy way to create your own instructions to better automate repetitive machine 
tasks. Included is information on macro directives and substitution symbols used as macro 
parameters. 
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Contains instructions for invoking the archiver, creating new archive libraries and modifying 
existing libraries. 


71 Archiver Developitient POW o..0<+<0bsvaiave ce ruaenave Pidaesadercdeasarderees 
72. ‘NavOlnig TS HICHWEr %isainds-n8 aa G na sngehaaand sha cA daieacetuaes 
ViSo- AVCHVEPESAMDIES yok icc dence adkGats dasa vde credo dade ste deranener das neaewns 
LINKEF DESCHIPUION a. ce ieis cpa tere oe arene eget ORs ein ORE eee ee OG eee en eG eee ee OG B-1| 


Describes the process of creating executable modules by combining COFF object files; 
describes how to invoke and use the linker, and presents a detailed example. 
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Chapter 1 


Introduction 


The TMS320C3x/C4x DSPs are supported by the following assembly 
language tools: 


_j Assembler 

_) Archiver 

_j Linker 

J Hex conversion utility 


This chapter shows how these tools fit into the general software tools develop- 
ment flow and gives a brief description of each tool. For convenience, it also 
summarizes the C compiler and debugging tools; however, the compiler and 
debugger are not shipped with the assembly language tools. For detailed 
information on the compiler and debugger and for complete descriptions of the 
TMS320C3x/C4x devices, refer to books listed in Related Documentation 
From Texas Instruments, page vi. 


The assembly language tools create and use object files in common object file 
format (COFF) to facilitate modular programming. Object files contain sepa- 
rate blocks (called sections) of code and data that you can load into TMS320 
memory spaces. You can program the TMS320 devices more efficiently if you 
have a basic understanding of COFF. Chapter 2, /ntroduction to Common 
Object File Format, discusses this object format in detail. 
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Software Development Tools Overview 


1.1 Software Development Tools Overview 
Figure 1-1 shows the assembly language development flow. The shaded 


portion highlights the most common development path; the other portions are 
optional. 


Figure 1-1. TMS320 Family Assembly Language Development Flow 
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1.2 Tools Descriptions 


| 


The C compiler translates C source code into TMS320C3x or 
TMS320C4x assembly language source code. The C compiler is not in- 
cluded as part of the assembly language tools package. 


The assembler translates assembly language source files into machine 
language object files. Source files can contain instructions, assembler 
directives, and macro directives. You can use assembler directives to con- 
trol various aspects of the assembly process, such as the source listing 
format, data alignment, and section content. 


The linker combines object files into a single executable object module. 
As it creates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files (cre- 
ated by the assembler) as input. It also accepts archiver library members 
and output modules created by a previous linker run. Linker directives 
allow you to combine object file sections, bind sections or symbols to ad- 
dresses or within memory ranges, and define or redefine global symbols. 


The archiver allows you to collect a group of files into a single archive file. 
For example, you can collect several macros together into a macro library. 
The assembler will search through the library and use the members that 
are called as macros by the source file. You can also use the archiver to 
collect a group of object files into an object library. The linker will include 
the members in the library that resolve external references during the link. 


The absolute lister accepts linked object files as input and creates .abs 
files as output. You assemble .abs files to produce a listing that contains 
absolute rather than relative addresses. Without the absolute lister, pro- 
ducing such a listing would be tedious and require many manual opera- 
tions. 


The main purpose of this development process is to produce a module that 
can be executed in a system that contains a TMS320 device. There are 
several debugging tools available for the various TMS320 devices: 


m The simulator is a software program that simulates TMS320 instruc- 
tions. The simulator can execute linked COFF object modules. The 
simulator is not included with the assembly language package. 


m The XDS (extended development support) emulator is a real-time, 
in-circuit emulator with the same screen-oriented interface as the 
software simulator. The emulator is not included with the assembly 
language package. 
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m@ The evaluation module (EVM) is a low-cost development board that 
provides full-speed in-circuit emulation and hardware debugging. The 
EVM is available now for the TMS320C8x devices and will be avail- 
able soon for the TMS320C4x devices. 


m TheC source debugger is a software interface to the simulator, emu- 
lator, and EVM. 


(1 The TMS320C3x/4x devices accept COFF files as input, but most 
EPROM programmers do not. The hex conversion utility converts a 
COFF object file into Tl-tagged, Intel, Motorola S1/S2/S3, or Tektronix 
object format. The converted file can be downloaded to an EPROM 
programmer. 


Chapter 2 


Introduction to Common Object File Format 


The assembler and linker create object files that can be executed by a 
TMS320C3x/C4x device. The format that these object files are in is called 
common object file format, or COFF. 


COFF makes modular programming easier because it encourages you to 
think in terms of blocks of code and data when you write an assembly language 
program. These blocks are known as sections. Both the assembler and the 
linker provide directives that allow you to create and manipulate sections. 


In addition to this chapter, Appendix A details COFF object file structure. For 
example, it describes the fields in a file header and the structure of a symbol 
table entry. Appendix A is useful mainly for those of you who are interested in 
the internal format of object files. 
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2.1 COFF File Types 


2.2 Sections 


The following types of COFF files exist: 


) COFFO 
) COFF1 
O COFF2 


Each COFF file type has a different header format. The data portions of the 
COFF files are identical. For details about the COFF file structure, see 
Appendix A, Common Object File Format. 


The TMS320C3x/C4x assembler and C compiler create COFF2 files. The 
linker can read and write all types of COFF files. By default, the linker creates 
COFF2 files. Use the —v linker option to specify a different format. The linker 
supports COFFO and COFF1 files for older versions of the assembler and C 
compiler only. 


The smallest unit of an object file is called a section. A section is a block of 
code or data that will ultimately occupy contiguous space in the 
TMS320C3x/C4x memory map. Each section of an object file is separate and 
distinct from the other sections. COFF object files always contain three default 
sections: 


.text usually contains executable code. 
data usually contains initialized data. 
-bss usually reserves space for uninitialized variables. 


In addition, the assembler and linker allow you to create, name, and link 
named sections that are used similarly to the .data, .text, and .bss sections. 


It is important to note that there are two basic types of sections: 


Initialized sections contain data or code. The .text and .data sections 
are initialized; named sections created with the 
.sect and .asect assembler directives are also in- 
itialized. 

Uninitialized sections reserve space in the memory map for uninitialized 
data. The .bss section is uninitialized; named sec- 
tions created with the .usect assembler directive 
are also uninitialized. 


Sections 


The assembler provides several directives that allow you to associate various 
portions of code and data with the appropriate sections. The assembler builds 
these sections during the assembly process, creating an object file that is or- 
ganized similarly to the object file shown in Figure 2-1. 


One of the linker’s functions is to relocate sections into the target memory map; 
this is called allocation. Because most systems contain several different 
types of memory, using sections can help you to use target memory more effi- 
ciently. All sections are independently relocatable; you can place different sec- 
tions into various blocks of target memory. For example, you can define a sec- 
tion that contains an initialization routine and then allocate the routine into a 
portion of the memory map that contains EPROM. 


Figure 2—1 shows the relationship between sections in an object file and a hy- 
pothetical target memory. 


Figure 2-1. Partitioning Memory Into Logical Blocks 
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2.3 How the Assembler Handles Sections 


2.3.1 


The assembler identifies the portions of an assembly language program that 
belong inasection. The assembler has six directives that support this function: 


-bss 
-usect 
-text 
.data 
-sect 
-asect 


ea Haye 


The .obss and .usect directives create uninitialized sections; the .text, .data, 
sect, and .asect directives create initialized sections. 


——_——ureeeneeerererererrrwrerrwerrwrewereeejreeeeeeeeeeerrwreeereeerwrerervrrweewrmraerrereeererwreeerwsreereeeeennnnanaaannnenaaaainapw 
Note: Default Section Directive 


If you don’t use any of the sections directives, the assembler assembles 


everything into the .text section. 
(ee ee | 


Uninitialized Sections 


Uninitialized sections reserve space in TMS320C3x/C4x memory; they are 
usually allocated into RAM. These sections have no actual contents in the 
object file; they simply reserve memory. A program can use this space at run 
time for creating and storing variables. 


Uninitialized data areas are built by using the .bss and .usect assembler 
directives. The .bss directive reserves space in the .bss section. The .usect 
directive reserves space in a specific uninitialized named section. Each time 
you invoke the .bss directive, the assembler reserves more space in the .bss 
section. Each time you invoke the .usect directive, the assembler reserves 
more space in the specified named section. 


The syntax for each directive is 


-bss symbol, size in words 


symbol .usect "section name”, size in words [alignment flag] 


How the Assembler Handles Sections 


symbol points to the first byte reserved by this invocation of the .bss 
or .usect directive. The symbol corresponds to the name of 
the variable for which you're reserving space. It can be ref- 
erenced by any other section and can also be declared as 
a global symbol (with the .global assembler directive). 


size is an absolute expression. The .bss directive reserves size 
words in the .bss section; the .usect directive reserves size 
words in section name. There is no default size for the .bss 
section. 


section name _ tells the assembler which named section to reserve space 
in. For more information about named sections, refer to 
subsection 2.3.3. 


blocking flag is an optional parameter. If present and nonzero, the flag 
means that this section will be blocked. Blocking is an ad- 
dress alignment mechanism similar to alignment, but 
weaker. It means a section is guaranteed not to cross a 
page boundary (128 words) if itis smaller than a page, and 
to start on a page boundary if it is larger than a page. This 
blocking applies to the section, not to the object declared 
with this instance of the .usect directive. 


alignment flag is an optional parameter. If present and nonzero, the sec- 
tion will be aligned to a long word boundary. 


The .text, .data, .sect, and .asect directives tell the assembler to stop 
assembling into the current section and begin assembling into the indicated 
section. The .bss and .usect directives, however, do not end the current 
section and begin a new one; they simply escape from the current section 
temporarily. The .bss and .usect directives can appear anywhere in an initial- 
ized section without affecting the contents of the initialized section. 


2.3.2 Initialized Sections 


Initialized sections contain executable code or initialized data. The contents 
of these sections are stored in the object file and placed in TMS320C3x/C4x 
memory when the program is loaded. Each initialized section is separately 
relocatable and may reference symbols that are defined in other sections. The 
linker automatically resolves these section-relative references. 
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Three directives tell the assembler to place code or data into a section. The 
syntax for each directive is 


text 
.data 


sect ’section name” [, value] 


When the assembler encounters one of these directives, it stops assembling 
into the current section; the directive acts as an implied “end current section” 
command. The assembler then assembles subsequent code into the section 
designated by the directive until it encounters another .text, .data, or .sect 
directive. 


Sections are built up through an iterative process. For example, when the as- 
sembler first encounters a .data directive, the .data section is empty. The state- 
ments following this first .data directive are assembled into the .data section 
(until the assembler encounters a .text, .sect, or .asect directive). Ifthe assem- 
bler encounters subsequent .data directives, it adds the statements following 
these .data directives to the statements that are already in the .data section. 
This creates a single .data section that can be allocated contiguously into 
memory. 


2.3.3 Named Sections 


Named sections are sections that youcreate. You can use them like the default 
.text, data, and .bss sections, but they are assembled separately from the de- 
fault sections. 


For example, repeated use of the .text directive builds up a single .text section 
in the object file. When linked, this .text section is allocated into memory as a 
single unit. Suppose there is a portion of executable code (perhaps an initiali- 
zation routine) that you don’t want allocated with .text. If you assemble this 
segment of code into a named section, it will be assembled separately from 
.text, and you will be able to allocate it into memory separately from .text. Note 
that you can also assemble initialized data that is separate from the .data sec- 
tion, and you can reserve space for uninitialized variables that is separate from 
the .bss section. 


Three directives let you create named sections: 


1 The .usect directive creates sections that are used like the .bss section. 
These sections reserve space in RAM for variables. 


(J The .sect directive creates sections that can contain code or data, similar 
to the default .text and .data sections. The .sect directive creates named 
sections with relocatable addresses. 


How the Assembler Handles Sections 


The syntax for each directive is: 


symbol .usect “section name”, size in words [, alignment flag] 


-sect “section name” |, value] 


The section name parameter is the name of the section. Section names are 
significant to 8 characters. You can create up to 32,767 separate named sec- 
tions. 


Each time you invoke one of these directives with a new name, you create a 
new named section. Each time you invoke one of these directives with aname 
that was already used, the assembler assembles code or data (or reserves 
space) into the section with that name. You cannot use the same names with 
different directives. That is, you cannot create a section with the .usect direc- 
tive and then try to use the same section with .sect. 
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2.3.4 Subsections 


Subsections are smaller sections within larger sections. Like sections, sub- 
sections can be manipulated by the linker. Subsections give you tighter control 
of the memory map. You can create subsections by using the .sect or .usect 
directive. The syntax for a subsection name is: 


section name:subsection name 


A subsection is identified by the base section name followed by a colon, then 
the name of the subsection. A subsection can be allocated separately or 
grouped with other sections using the same base name. For example, to 
create a subsection called _ func within the .text section, enter the following: 


-sect ”.text:_func” 
You can allocate _func separately or within all the .text sections. 


You can create two types of subsections: 


(1 Initialized subsections are created using the .sect directive. See subsec- 
tion 2.3.2, Initialized Sections, on page 2-5. 


[4 Uninitialized subsections are created using the .usect directive. See 
subsection 2.3.1, Uninitialized Sections, on page 2-4. 


Subsections are allocated in the same manner as sections. See Section 8.7, 
The SECTIONS Directive, on page 8-27 for more information. 


2.3.5 Section Program Counters 


The assembler maintains a separate program counter for each section. These 
program counters are known as section program counters, or SPCs. 


An SPC represents the current address within a section of code or data. 
Initially, the assembler sets each SPC to 0. As the assembler fills a section with 
code or data, it increments the appropriate SPC. If you resume assembling into 
a section, the assembler remembers the appropriate SPC’s previous value 
and continues incrementing the SPC at that point. 


The assembler treats each section as if it begins at address 0; the linker relo- 
cates each section according to its final location in the memory map. 


How the Assembler Handles Sections 


2.3.6 An Example That Uses Sections Directives 


Figure 2-1 shows how you can build COFF sections incrementally, using the 
sections directives to swap back and forth between the different sections. You 
can use sections directives to 


_j) Begin assembling into a section for the first time, or 


_j Continue assembling into a section that already contains code. In this 
case, the assembler simply appends the new code to the code that is al- 
ready in the section. 


The format in this example is a listing file. Example 2—1 shows how the SPCs 
are modified during assembly. A line in a listing file has four fields: 


Field 1 contains the source code line counter. 

Field 2 contains the section program counter. 

Field 3 contains the object code. 

Field 4 contains the original source statement. 
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Example 2-1. Using Section Directives 


1, KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKK 
2 ** Assemble an initialized table into data ** 
3 kaka Kh KKK Kh KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 
4 00000000 .data 
5 00000000 00000011 coeff -word Ollh, 022h, 033h 
00000001 00000022 
00000002 00000033 
6 kaka KKK KK Kh KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 
7 **x Reserve space in .bss for two variables ** 
8 kaka K KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 
9 00000000 .bss Vary 1 
10 00000001 -bss buffer, 10 
11 
ple KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKK 
13 bid Still in data — 
14 kak KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK 
15 00000003 00000123 ptr -word 0123h 
16 
17 KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKKKKKKKKKK 
18 ae Assemble code into .text section oe 
19 Kaka KK KKK Kh KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 
20 00000000 text 
21 00000000 0869000a add: LDI 10,AR1 
22 00000001 08610000 LDI 0,R1 
23 00000002 aloop: 
24 00000002 02412001 ADDI *ARO++,R1 
25 00000003 6e46fffe DBNZ AR1,aloop 
26 00000004 15210000- STL R1, @varl 
27 
28 KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKKKKKKKKKK 
29 — Assemble another initialized table ** 
30 ae into the data section kal 
37 kak Kk Kh KKK Kaka K KKK kK kK KK KKK KKK KKK KKK KKK KKK KKK KKK 
32 00000004 .data 
33 00000004 000000aa ivals -word OAAh, OBBh, OCCh 
00000005 000000bb 
00000006 000000cc 
34 kak K KKK KKK K KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 
35 ** Define another section for more variables** 
36 KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKK 
37 00000000 var2 -usect "newvars”,1 
38 00000001 inbuf -usect "newvars”,7 
39 
40 Kaa K RK KKK KKK KKK KKK Ka KKK KKK KKK KKK KK KK KKK KK KK KKK 
41 ** Assemble more code into .text section *% 
42 Kaa K KKK KKK KKK KKK KKK Kk KKK KKK KKK KKK KKK KKK KKK KK KK 
43 00000005 text 
44 00000005 0869000a mpy: LDI 10,AR1 
45 00000006 08610000 LDI 0,R1 
46 00000007 mloop: 
47 00000007 0Oac12001 MPYI *ARO++,R1 
48 00000008 6e46fffe DBNZ AR1,mloop 
49 00000009 15210000- Srl R1, @var2 
50 
Ball KKK KKK KKK KK KK KKK KKK KKK KKK KKKKKKKKK KKK KKK KKK KKK 
52 ** Define a nameed section for int. vectors ** 
53 Kaka K KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KK KKK KK KK KK 
54 00000000 -sect “vectors” 
55: 00000000 00000000’ -word add, mpy 
00000001 00000005’ 
Field 1 Field 2 Field 3 Field 4 
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As Figure 2—2 shows, the file in Example 2-1 creates five sections: 


.text contains 10 words of object code. 
.data contains 7 words of object code. 
vectors is anamed section created with the .sect directive; it contains 2 


words of initialized data. 


-bss reserves 11 words in memory. 


newvars is anamed section created with the .usect directive; it reserves 


8 words in memory. 


The second column shows the object code that is assembled into these sec- 
tions; the first column shows the source statements that generated the object 


code. 


Figure 2-2. Object Code Generated by Example 2-1 


Line Numbers Object Code 
21 0869000A 
22 08610000 
24 02412001 
25 6E46FFFE 
26 15210000 
44 0869000A 
45 0861000A 
47 0AC12001 
48 6E46FFFE 
49 15210000 
5 00000011 
5 00000022 
5 00000033 
15 00000123 
33 O00000AA 
37 000000BB 
33 000000CC 


55 00000000 
55 00000005 
9,10 No data 


11 words 
reserved 


37, 38 No data 8 
words 
reserved 


Section 


.text section 


.data section 


vectors 


.bss 


newvars 
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2.4 How the Linker Handles Sections 


2.4.1 
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The linker has two main functions in regard to sections. First, the linker uses 
the sections in COFF object files as building blocks; it combines input sections 
(when more than one file is being linked) to create output sections in an exe- 
cutable COFF output module. Second, the linker chooses memory addresses 
for the output sections. 


The linker provides two directives that support these functions: 


(1 The MEMORY directive allows you to define the memory map of a target 
system. You can name portions of memory and specify their starting ad- 
dresses and their lengths. 


(1 The SECTIONS directive tells the linker how to combine input sections 
and where to place the output sections in memory. 


It is not always necessary to use linker directives. If you don’t use them, the 
linker uses the target processor’s default allocation algorithm described in 
subsection 2.4.1. When you do use linker directives, you must specify them 
in a linker command file. 


Refer to the following sections for more information about linker command files 
and linker directives: 


Section Pag 
8.4 Linker Command Files .......... 00.0.0. ccc cece eee eee ees 
8.6 The MEMORY Directive .......... 0.0.0. ccc ees 
8.7 The SECTIONS Directive ......... 0.0.00. cc ees 
8.11 Default Allocation ...... 0.0.0... en ee nee 


Default Allocation 


You can link files without specifying a MEMORY or SECTIONS directive. The 
linker uses a default model to combine sections (if necessary) and allocate 
them into memory. When using the default model, the linker 


1) Assumes that memory begins at address Oh. 


) 
2) Assumes that 232 words are available to allocate object code into. 
3) Allocates .text into memory, beginning at address 0. 
4) Allocates .data into memory, immediately following .text. 
5) Allocates .bss into memory, immediately following .data. 
6) Allocates all named sections into memory, immediately following .bss. 


Named sections are allocated in the order that they're encountered in the 
input files. 


How the Linker Handles Sections 


Figure 2-3 shows how a single file would be allocated into memory by using 
default allocation for the TMS320C3x/C4x. Note that the linker does not actu- 
ally place object code into memory; it assigns addresses to sections so that 
a loader can place the code in memory. 


Figure 2-3. Default Allocation for the Object Code in Figure 2-2 


Object Code Section 
00000000h 
text 0869000A 
08610000 
02412001 
6E46FFFE ; 
15210000 text size = 10 
0869000A ——— words 
0861000A 
0AC12001 
6E46FFFE 
15210000 0000000Ah 
data 00000011 size = 7 
00000022 -— data words 
00000033 
00000123 
000000BB 
000000CC 
bss size = 11 
vectors 00000000 words 
00000005 
.bss No data 
11 words 0000001Ch 
reserved 
size =8 
newvars No data ewes, words 
8 words 
reserved 
Li 00000024h 
vectors size = 2 
words 


As Figure 2-3 shows, the linker: 


1) Allocates the .text section first, beginning at address Oh. The .text section 
contains 10 words of object code. 


2) Allocates the .data section next, beginning at address Ah. The .data sec- 
tion contains 7 words of object code. 


3) Allocates the .bss section third, beginning at address 11h. The .bss sec- 
tion reserves 11 words in memory. 
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4) Allocates the named section, newvars, at address 1Ch. (newvars was the 
first named section encountered in the original input file. See 
Example 2-1.) The newvars section reserves 8 words in memory. 


5) Allocates the named section vectors at address 24h. The vectors section 
contains 2 words of object code. 


Figure 2—4 shows a simple example of how twofiles would be linked together. 
When you link several files using the default algorithm, the linker combines all 
input sections that have the same name into one output section that has this 
same name. For example, the linker combines the .text sections from two input 
files to create one .text output section. 


Figure 2-4. Combining Input Sections From Two Files (Default Allocation) 
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newvars 


file2 
vectors 
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In Figure 2-4, file1.obj and file2.obj each contain the .text, .data, and .bss 
default sections and a named section called newvars; file2.obj also contains 
a named section called vectors. As Figure 2—4 shows, the linker: 


1) Combines file1.text with file2.text to form one .text output section. The 
.text output section is allocated at address Oh. 


2) Combines file? .data with file2 .datato form the .data output section. The 
.data output section is allocated following the .text output section. 


3) Combines file7.bss with file2.bss to form the .bss output section. The .bss 
output section is allocated following the .data output section. 


4) Combines file? newvars with file2 newvars to form the newvars output 
section. (The newvars section is the first named section that is encoun- 
tered during the link, so it is allocated before the second named section, 
vectors.) The newvars output section is allocated following the .bss output 
section. 


5) Allocates the vectors section from file2 after the newvars section. 


For more information about default allocation algorithms, refer to Section 8.11 
on page 8-47. 


2.4.2 Placing Sections in the Memory Map 


Figure 2-3 and Figure 2-4 illustrate the linker’s default methods for combining 
sections and allocating them into memory. Sometimes you may not want to 
use the default setup. For example, you may not want to combine all of the .text 
sections into a single .text section. Or, you might want a named section placed 
at address 40h instead of the .text section. Most memory maps are composed 
of various types of memories (DRAM, ROM, EPROM, etc.) in varying 
amounts; you may want to place a section in a particular type of memory. 


The next two illustrations show another possible combination of the sections 
from Figure 2-3: 


Example 2-2 contains linker MEMORY and SECTIONS definitions. 


Figure 2-5 shows how the sections from Example 2-2 are allocated into the 
memory map. 
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Example 2-2. MEMORY and SECTIONS Directives for Figure 2-5 


[KKK KK KK KK I HI I I I I I I I I A I I I I I A I A I A I He / 


/* Linker command file ERK: 
[BRK RK KK KK KK I I I I I I A I A A A A I a / 


MEMORY 

{ 
VECS: origin = 00000000h length = 40h 
ROM: origin = 00000040h length = FCOh 
RAMO: origin = 00801000h length = 400h 
RAM1: origin = 00801400h length = 400h 


SECTIONS 
{ 
vectors : load = 0000000h 
-text : load = ROM 
-data : load = ROM 
-bss : load = RAMO 


newvars:load = RAMI 


(1) The MEMORY directive in Example 2—2 defines four memory ranges: 


VECS 
ROM 

RAMO 
RAM1 


The origin for each of these ranges identifies the range’s starting address 
in memory. The /ength specifies the length of the range. For example, 
memory range RAMO, with starting address 00801000h and length 400h, 
defines the addresses 00801000h through 008013FFh in memory. 


(1 The SECTIONS directive in Example 2—2 defines the order in which the 
sections are allocated into memory. The vectors section must begin at 
address 0. Both .text and .data are allocated into the ROM area that was 
defined by the MEMORY directive. The .bss section is allocated into 
RAMO, and newvars is allocated into RAM1. 
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Figure 2-5. Rearranging the Memory Map From Figure 2-3 


Object Code 


text 0869000A 
08610000 
02412001 
6E46FFFE 
15210000 


0869000A 
0861000A 
0AC12001 
6E46FFFE 
15210000 


data 00000011 
00000022 
00000033 
00000123 
O00000AA 
000000BB 
000000CC 


vectors 00000000 
00000005 

.bss No data 

11 words 


reserved 


newvars 


No data 8 
words 
reserved 


Section 


vectors 
2 words 


unused memory 


data 
(size = 7 
words) 


unused memory 


.bss 
(size = 11 


words) 


unused memory 


newvars 
(size = 8 
words) 


unused memory 


00000000h 
(interrupt vectors) 
00000002h 


00000040h 
(internal ROM) 


0000004Ah 


00000051h 


00801000h 
(RAM block0) 


00801400h 
(RAM block1) 


00801408h 


00801800h 
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2.5 Relocation 


The assembler treats each section as if it begins at address 0. All relocatable 
symbols (labels) are relative to address 0 in their sections. Of course, all 
sections can’t actually begin at address 0 in memory, so the linker relocates 
sections by: 


[1 Allocating sections into the memory map so that they begin at the 
appropriate address 


(4 Adjusting symbol values to correspond to the new section addresses 


(41 Adjusting references to relocated symbols to reflect the adjusted symbol 
values 


The linker uses relocation entries to adjust references to symbol values. The 
assembler creates a relocation entry each time a relocatable symbol is refer- 
enced. The linker then uses these entries to patch the references after the 
symbols are relocated. Example 2-3 contains a code segment that generates 
relocation entries. 


Example 2-3. Code That Generates Relocation Entries 


Al .cef x 

2 00000000 -text 

3 00000000 60FFFFFF'! BR x ; Generates a relocation entry 
4 00000001 08200002’ LDI @Y,RO ; Generates a relocation entry 
5 00000002 06000000 Y: IDLE 


In Example 2-3, both symbols X and Y are relocatable. X is defined in some 
other module; Yis defined in the .text section of this module. When assembled, 
X has a value of 0 (the assembler assumes all undefined external symbols 
have values of 0) and Y has a value of 2 (relative to address 0 in the .text sec- 
tion). The assembler generates two relocation entries, one for X and one for 
Y. The reference to X is an external reference (indicated by the ! character in 
the listing). The reference to Y is to an internally defined relocatable symbol 
(indicated by the ’ character in the listing). 


After linking, suppose that X is relocated to address 100h. Suppose also that 
the .text section is relocated to begin at address 200h; Ynow has a relocated 
value of 204h. The linker uses the two relocation entries to patch the two refer- 
ences in the object code: 


60000000 BR xX becomes 60000100 
08200002 LDI @Y,RO becomes 08200202 
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Each section in a COFF object file has a table of relocation entries. The table 
contains one relocation entry for each relocatable reference in the section. The 
linker usually removes relocation entries after it uses them. This prevents the 
output file from being relocated again (if it is relinked or when it is loaded). A 
file that contains no relocation entries is an absolute file (all of its addresses 
are absolute addresses). If you want the linker to retain relocation entries, 
invoke the linker with the —r option. 
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2.6 Runtime Relocation 


It may be necessary or desirable at times to load code into one area of memory 
and run it in another. For example, you may have performance critical code in 
a ROM-based system. The code must be loaded into ROM but would run much 
faster if it were in RAM. 


The linker provides a simple way to specify this. In the SECTIONS directive, 
you can optionally direct the linker to allocate a section twice: once to set its 
load address, and again to set its run address. 


Use the /oad keyword for the load address and the run keyword for the run 
address. 


The load address determines where a loader will place the raw data for the 
section. Any references to the section (such as labels in it) refer to its run ad- 
dress. The application must copy the section from its load address to its run 
address; this does not happen automatically just because you specify a sepa- 
rate run address. 


If you provide only one allocation (either load or run) for a section, the section 
is allocated only once and willload andrun at the same address. If you provide 
both allocations, the section is actually allocated as if it were two different sec- 
tions of the same size. 


Uninitialized sections (such as .bss) are not loaded, so the only address of sig- 
nificance is the run address. The linker allocates uninitialized sections only 
once: if you specify both run and load addresses, the linker warns you and ig- 
nores the load address. 


For a complete description of runtime relocation, see Section 8.8 on 
page 8-35. 


Loading a Program 


2.7 Loading a Program 


The linker produces executable COFF object modules. An executable object 
file has the same COFF format as object files that are used as linker input; how- 
ever, the sections in an executable object file are combined and relocated to 
fit into target memory. 


In order to run a program, the data in the executable object module must be 
transferred, or loaded, into target system memory. 


Several methods can be used for loading a program, depending on the execu- 
tion environment. Some of the more common situations are listed below. 


LJ The TMS320C3x/C4x debugging tools, including the software simulator, 
XDS emulator, and software development system, have built-in loaders. 
Each of these tools has a LOAD command that invokes a COFF loader; 
the loader reads the executable file and copies the program into target 
memory. 


L] Ifyou are using a ROM- or EPROM-based system, you can use the object 
format converter, which is shipped as part of the assembly language pack- 
age, to convert the executable COFF object module into one of several 
hexadecimal object file formats. You can then use the converted file with 
an EPROM programmer to burn the program into an EPROM. 


LJ Some TMS320C3x/C4x programs are loaded under the control of an oper- 
ating system or monitor software running directly on the target system. In 
this type of application, the target system usually has an interface to the 
file system on which the executable module is stored. You must write a 
custom loader for this type of system. Refer to Appendix A for supplemen- 
tary information about the internal format of COFF object files. The loader 
must comprehend the file system (in order to access the file) as well as the 
memory organization of the target system (to load the program into mem- 
ory). 


Source code for the TMS320C3x/C4x COFF loader is available through the 
TI DSP bulletin board (call the DSP hotline listed in the front of this manual for 
instructions). This loader provides all the basic mechanisms for reading a 
TMS320C3x/C4x COFF file and loading it into a target system. A simple inter- 
face allows customization to fit the requirements of most applications. 
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2.8 Symbols in a COFF File 


A COFF file contains a symbol table that stores information about symbols in 
the program. The linker uses this table when it performs relocation. Debugging 
tools can also use the symbol table to provide symbolic debugging. 


2.8.1. External Symbols 


External symbols are symbols that are defined in one module and referenced 

in another module. You can use the .global directive to identify symbols as 

external. In a source module, an external symbol can be either a ref or def: 

Defined (DEF) Defined in the current module and used in another 
module 

Referenced (REF) Referenced in the current module, but defined in an- 
other module 


The following code segment illustrates these definitions. 


-global x ; DEF of x 
-global y ; REF of y 

x: LDI RO,R1 ; Define x 
LDI @y, RO ; Reference y 


The .global definition of x says that itis an external symbol defined in this mod- 
ule and that other modules can reference x. The .global definition of ysays that 
it is an undefined symbol that is defined in some other module. 


The assembler places both x and y in the object file's symbol table. When the 
file is linked with other object files, the entry for x defines unresolved refer- 
ences to x from other files. The entry for y causes the linker to look through the 
symbol tables of other files for y's definition. 


The linker must match all references with corresponding definitions. If the 
linker cannot find a symbol’s definition, it prints an error message about the 
unresolved reference. This type of error prevents the linker from creating an 
executable object module. 


2.8.2 The Symbol Table 


The assembler always generates an entry in the symbol table when it encoun- 
ters an external symbol (both definitions and references). The assembler also 
creates special symbols that point to the beginning of each section; the linker 
uses these symbols to relocate references to other symbols in a section. 


The assembler does not usually create symbol table entries for any other type 
of symbol, because the linker does not use them. For example, labels are not 
included in the symbol table unless they are declared with .global. For sym- 
bolic debugging purposes, it is sometimes useful to have entries in the symbol 
table for each symbol in a program. To accomplish this, invoke the assembler 
with the —s option. 


Chapter 3 


Assembler Description 


The assembler translates assembly-language source files into object files. 
These files are in common object file format (COFF), which is discussed in 
Chapter 2 and Appendix A. Source files can contain the following assembly 
language elements: 


Assembler directives described in Chapter 4 
Assembly language instructions described in Chapter 5 
Macro directives described in Chapter 6 
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3.1. Assembler Overview 


The assembler does the following: 


a 


L 


Processes the source statements in a text file to produce a relocatable 
object file 


Produces a source listing (if requested) and provides you with control over 
this listing 


Allows you to segment your code into sections and maintain an SPC 
(section program counter) for each section of object code 


Defines and references global symbols and appends a cross-reference 
listing to the source listing (if requested) 


Assembles conditional blocks 
Supports macros, allowing you to define macros inline or in a library 


Allows you to assemble TMS320C3x and TMS320C4x code 


Assembler Development Flow 


3.2 Assembler Development Flow 


Figure 3-1 illustrates the assembler’s role in the assembly language develop- 
ment flow. The assembler accepts assembly language source files as input. 
The TMS320C3x/C4x floating-point assembler also accepts assembly 
language files created by the TMS320C3x/C4x C compiler. 


Figure 3-1. Assembler Development Flow 
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3.3 


Invoking the Assembler 


To invoke the assembler, enter the following: 


asm30_ [input file [object file [listing file||] [-options] 


asm30 


input file 


object file 


listing file 


options 


is the command that invokes the assembler. 


names the assembly language source file. If you do not supply 
an extension for input file, the assembler assumes that the in- 
put file has the default extension .asm. If you do not supply an 
input filename when you invoke the assembler, the assembler 
will prompt you for one. 


names the object file that the assembler creates. If you do not 
supply an extension, the assembler uses .obj as a default ex- 
tension. If you do not supply an object file, the assembler cre- 
ates a file that uses the input file name with the .obj extension. 


names the optional listing file that the assembler can create. 
If you do not supply aname for alisting file, the assembler does 
not create one unless you use the -I option. In this case, the 
assembler uses the input filename and, if you do not supply an 
extension, the assembler uses .Ist as a default extension. 


identify the assembler options that you want to use. 


Options are not case sensitive and can appear anywhere on 
the command line, following the command. Precede each op- 
tion with a hyphen (—). You can string the options together; for 
example, —Ic is equivalent to -I—c. Note that the assembler ac- 
cepts —mbir, which is equivalent to -mb —mi —mr. However, it 
will not accept —mbirq, because the “q” is read as —mq and not 
as —q. The valid assembler options are as follows: 


-a creates an absolute listing. When you use 
—a, the assembler does not produce an ob- 
ject file. The —a option is used in conjunction 
with the absolute lister. 


-c makes case insignificant in the assembly 
language files. For example, —c will make 
the symbols ABC and abc equivalent. /f you 
do not use this option, case is significant 
(default). 


}-ednamef=def] _predefines the constant name for the as- 
sembler. This is equivalent — to 
inserting #define name def at the top of 
each source file. If the optional def is 
omitted, -dname sets name equal to 1. 


—mi 


—mr 


-Ss 


—uname 


Invoking the Assembler 


specifies a directory where the assembler 
can find files named by the .copy, .include, 
or .mlib directives. The format of the —i op- 
tion is —ipathname. You can specify up to 10 
directories in this manner; each pathname 
must be preceded by the —i option. 


(lowercase “L”) produces a listing file. 


predefines the .BIGMODEL symbol. This 
option is used when assembly code will be 
linked with a C module that uses the large 
memory runtime model. 


predefines the .C30INTERRUPT symbol. 
This option is used when the assembly 
code will be used with code compiled with 
the shell’s —mi option. 


predefines the .REGPARM symbol. This 
option is used when assembly code will be 
linked with a C module that uses the regis- 
ter-argument runtime model. 


predefines the .TMX320C40 symbol. This 
option is used to support legacy assembly 
code and may be removed in a future re- 
lease. 


(quiet) suppresses the banner and all pro- 
gress information. 


puts all defined symbols in the object file’s 
symbol table. The assembler usually puts 
only global symbols into the symbol table. 
When you use —s, symbols that are defined 
as labels or as assembly-time constants are 
also placed in the symbol table. See also 
subsection 2.8.2 on page 2-22. 


overrides any —d options for the specified 
constant and undefines the predefined 
constant name. 
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-V 


—msrevx 


—-X 


3.4 Porting Upward Compatible Code 


specifies a version. The version tells the as- 
sembler which of the following 
TMS320C3x/C4x devices it should produce 
code for (The default is —v30): 


-v30 selects the TMS320C30 
-v31 selects the TMS320C31 
—v32 selects the TMS320C32 
-v40 selects the TMS320C40 
-v44 selects the TMS320C44 


the x = 1, 2, 3, etc. 


specifies the silicon revision of the target 
chip to enable additional functionality for 
more recent silicon releases. Used in con- 
junction with —v flag. 


Example: 


—msrev6 -—v31: enable new (1996) ’C31 
parallel instructions 


—msrev2 -v32: enable new (1996) ’C32 
parallel instructions 


produces a cross-reference table and ap- 
pends it to the end of the listing file. If you do 
not request a listing file, the assembler cre- 
ates one anyway, but the listing contains 
only the cross-reference table. 


The floating-point processors in the TMS320C3x/C4x family are upwardly 
source code compatible. For example, code originally written for the 
TMS320C30 can be assembled for the TMS320C40 with —-v40 assembler op- 
tion. The —v version option is explained in detail on page 3-6. 


All of the processors are capable of handling upwardly ported code as long as 
the target processor’s number is the same as or greater than the original target 
processor. Porting code downward, however, produces undefined results; in 
most cases the code will fail to assemble. 


The TMS320C3x and TMS320C4x families are not object code compatible. 
Code for the ’C3x must be reassembled in order to run on a ’C4x and vice 


versa. 
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3.5 Naming Alternate Directories for Assembler Input 


The .copy, .include, and .mlib directives tell the assembler to use code from 
external files. The .copy and .include directives tell the assembler to read 
source statements from another file, and the .mlib directive names a library 
that contains macro functions. Chapter 4, Assembler Directives, contains ex- 
amples of the .copy, .include, and .mlib directives. The syntax for these direc- 
tives is 


copy “filename” 


.include “filename” 


.mlib “filename” 


The filename names a copy/include file that the assembler reads statements 
from or a macro library that contains macro definitions. The filename may be 
a complete pathname or a filename with no path information. If you provide a 
pathname, the assembler uses that path and does not look for the file in any 
other directories. If you do not provide path information, the assembler 
searches for the file in the following directories: 


1) The directory that contains the current source file. The current source file 
is the file being assembled when the .copy, .include, or .mlib directive is 
encountered. 


2) Any directories named with the —i assembler option. 
3) Any directories set with the environment variable A_DIR. 
You can augment the assembler’s directory search algorithm by using the —i 
assembler option or the environment variable. 
3.5.1 -i Assembler Option 


The -i assembler option names an alternate directory that contains copy/ 
include files or macro libraries. The format of the —i option is as follows: 


asm30 —-ipathname source filename 


You can use up to 10-i options per invocation; each — option names one path- 
name. In assembly source, you can use the .copy, .include, or .mlib directive 
without specifying any path information. If the assembler doesn't find the file 
in the directory that contains the current source file, it searches the paths pro- 
vided by the — options. 
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For example, assume that a file called source.asm is in the current directory; 
source.asm contains the following directive statement: 


-copy "copy.asm” 


Pathname for copy.asm Invocation Command 
DOS c:\dsp\files\copy.asm asm30 -ic:\dsp\files source.asm 
UNIX /dsp/files/copy.asm asm30 -i/dsp/files source.asm 


The assembler first searches for copy.asm in the current directory because 
source.asm is in the current directory. Then, the assembler searches in the di- 
rectory named with the —i option. 


3.5.2 Environment Variable (A_DIR) 


Anenvironment variable is a system symbol that you define and assign a string 
to. The assembler uses the environment variable A_DIR to name alternate di- 
rectories that contain copy/include files or macro libraries. The command for 
assigning the environment variable is as follows: 


Invocation Command 

DOS set | A_DIR=pathname;another pathname ... 

UNIX setenv A_DIR ”pathname;another pathname...” 
The pathnames are directories that contain copy/include files or macro librar- 
ies. You can separate the pathnames with a semicolon or with blanks. In as- 
sembly source, you can use the .copy, .include, or .mlib directive without speci- 
fying any path information. If the assembler doesn’t find the file in the directory 


that contains the current source file or in directories named by —, it searches 
the paths named by the environment variable. 
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For example, assume that a file called source.asm contains these statements: 


-copy “copyl.asm” 
-copy “copy2.asm” 


Pathname Invocation Command 
DOS c:\320\files\copyl.asm set A_DIR=c:\dsys 
c:\dsys\copy2.asm asm30 -ic:\320\files source.asm 
UNIX /320/files/copyl.asm set A_DIR /dsys 
/dsys/copy2.asm asm30 -i/320/files source.asm 


The assembler first searches for copy1.asm and copy2.asm in the current 
directory because source.asm is in the current directory. Then, the assembler 
searches in the directory named with the —i option and finds copy1.asm. Fi- 
nally, the assembler searches the directory named with A_DIR and finds 
copy2.asm. 


Note that the environment variable remains set until you reboot the system or 
reset the variable by entering one of these commands: 


DOS set A_DIR= 


UNIX ~=sunsetenv A_DIR 
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3.6 Source Statement Format 


3.6.1 
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Label Field 


TMS320C3x/C4x assembly language source programs consist of source 
statements that can contain assembler directives, assembly language instruc- 
tions, macro directives, and comments. Source statement lines can be as long 
as the source file format allows, but the assembler reads up to 200 characters 
per line. Ifa statement contains more than 200 characters, the assembler trun- 
cates the line and issues a warning. 


The next several lines show examples of source statements: 


SYM1 .set OA5h ; Symbol SYM = OA5Sh 
Begin: ADDI SYM+5,R1 ; Add (SYM+5) to the contents of R1 
LDI R1,R2 ; Move contents of R1 to R2 


A source statement can contain four ordered fields. The general syntax for 
source statements is as follows: 


[/abe!] [:] mnemonic [operand list] [;comment] 

Follow these guidelines: 

_j Allstatements must begin with a label, a blank, an asterisk, ora semicolon. 
(1 Labels are optional; if used, they must begin in column 1. 


(1 One or more blanks must separate each field. Note that tab characters are 
equivalent to blanks. 


_} Comments are optional. Comments that begin in column 1 can begin with 
an asterisk or a semicolon (* or ;), but comments that begin in any other 
column must begin with a semicolon. 


Labels are optional for all assembly language instructions and for most (but 
not all) assembler directives. When used, a label must begin in column 1 of 
a source statement. A label can contain up to 32 alphanumeric characters (A— 
Z, a-z, 0-9, _, and $). Labels are case sensitive, and the first character cannot 
be a number. A label can be followed by a colon (:); the colon is not treated as 
part of the label name. If you don’t use a label, then the first character position 
must contain a blank, a semicolon, or an asterisk. 


When you use a label, its value is the current value of the section program 
counter (the label points to the statement it’s associated with). If, for example, 
you use the .word directive to initialize several words, a label would point to 
the first word. In the following example, the label Start has the value 40h. 


Source Statement Format 


2 0000003F *Assume some other code was assembled 
3 00000040 OOOO000A Start: .word OAh, 3,7 

00000041 00000003 

00000042 00000007 


A label on a line by itself is a valid statement. It assigns the current value of 
the section program counter to the label; this is equivalent to the following 
directive statement: 


label .set S$; S$ provides the current value of the SPC 


When a label appears on a line by itself, it points to the instruction on the next 
line (the SPC is not incremented): 


5 00000050 Here: 
6 00000050 08010000 LDI RO, Rl 


3.6.2 Mnemonic Field 


The mnemonic field follows the label field. The mnemonic field cannot start in 
column 1, or it would be interpreted as a label. The mnemonic field can contain 
one of the following opcodes: 


(J Machine-instruction mnemonic (such as ADDI, MPYF, LDI) 


Assembler directive (such as .data, .list, .set) 


J 
Li Macro directive (such as .macro, .loop, .endloop) 
J 


A macro invocation 


3.6.3 Operand Field 


The operand field is a list of operands that follow the mnemonic field. An 
operand can be a constant (see Section 3.7), a symbol (see Section 3.9), or 
a combination of constants and symbols in an expression. You must separate 
operands with commas. 


3.6.4 Comment Field 


Acomment can begin in any column and extends to the end of the source line. 
Acommentcan contain any ASCII character, including blanks. Comments are 
printed in the assembly source listing, but they do not affect the assembly. 


Asource statement that contains only acommentis valid. If it begins in column 
1, it can start with a ; or a*. Comments that begin anywhere else on the line 
must begin with a ;. The * symbol identifies a comment only if it appears in col- 
umn 1. 
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3.7 Constants 


The assembler supports seven types of constants: 


Binary integer constants 

Octal integer constants 
Decimal integer constants 
Hexadecimal integer constants 
Floating-point constants 
Character constants 
Assembly-time constants 


a 


The assembler maintains each constant internally as a 32-bit quantity. Note 
that constants are not sign extended. For example, the constant OFFFFH is 
equal to OOOOFFFF16¢ or 65,5354 9; it does not equal —1. 


3.7.1. Binary Integers 


A binary integer constant is a string of up to 32 binary digits (Os and 1s) fol- 
lowed by the suffix B (or b). If less than 32 digits are specified, the assembler 
right-justifies the value and zero-fills the unspecified bits. Examples of valid 
binary constants include: 


00000000B_ Constant equal to 0 

0100000b Constant equal to 3249 or 2046 
01b Constant equal to 1 

11111000B Constant equal to 24849 or OF 846 


3.7.2 Octal Integers 


An octal integer constantis a string of up to 11 octal digits (0 through 7) followed 
by the suffix Q (or q). Examples of valid octal constants include: 


10Q Constant equal to 8 
100000Q Constant equal to 32,7684 9 or 800046 
226Q Constant equal to 15049 or 9646 


3.7.3 Decimal Integers 
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A decimal integer constant is a string of decimal digits, ranging from 
—2,147,483,647 to 4,294,967,295. Examples of valid decimal constants 
include: 


1000 Constant equal to 100019 or 3E84¢ 
-32768 Constant equal to -32,768 49 or 800046 
25 Constant equal to 2549 or 1946 


Constants 


3.7.4 Hexadecimal Integers 


A hexadecimal integer constant is a string of up to 8 hexadecimal digits fol- 
lowed by the suffix H (or h). Hexadecimal digits include the decimal values 0-9 
and the letters A-F and a-f. A hexadecimal constant must begin with a decimal 
value (0-9). If less than 8 hexadecimal digits are specified, the assembler 
right-justifies the bits. Examples of valid hexadecimal constants include: 


78h = Constant equal to 12049 or 007846 
OFh Constant equal to 1549 or OO0F 16 
37ACH Constant equal to 14,25249 or 37AC1¢ 


3.7.5 Character Constants 


A character constant is a string of 1 to 4 characters enclosed in single quotes. 
The characters are represented internally as 8-bit ASCII characters. Two con- 
secutive single quotes are required to represent each single quote within a 
character constant. A character constant consisting only of two single quotes 
(no letter) is valid and is assigned the value 0. If more than one character is 
specified, the assembler packs them into a 32-bit word, starting with the least- 
significant byte. If fewer than four characters is specified, the assembler right- 
justifies the bits. Examples of valid character constants include: 


‘ab’ Represented internally as 0000626116 
°C’ Represented internally as 0000004316 
”D’ Represented internally as 0000442716 
"abed’ Represented internally as 6463626116 


Note the difference between character constants and character strings 
(Section 3.8 discusses character strings). A character constant represents a 
single integer value; a string is a list of characters. 


3.7.6 Floating-Point Constants 


A floating-point constant is a string of decimal digits, followed by an optional 
decimal point, fractional portion, and exponent portion. The syntax for a 
floating-point number is: 


[+|- ] [nnn]. [ nnn [ Ble [ +|- ] nnn] J 


where nnnis a string of decimal digits. A floating-point constant may be pre- 
ceded with a + or a—. You must specify a decimal point; for example, 3.e5 is 
valid, but 3e5 is illegal. The exponent indicates a power of 10. 
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Valid floating-point constants include: 
3.0 

3.14 

3 

—0.314e13 

+314,59e-2 


For more information about floating-point format, refer to the TMS320C3x 
User’s Guide and the TMS320C4x User’s Guide. 


3.7.7. Assembly-Time Constants 
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If you use the .set directive to assign a constant value to a symbol, the symbol 
becomes an assembly-time constant. In order to use this constant in expres- 
sions, the value that is assigned to it must be absolute. For example: 


sym -set 3 
LDI sym, RO ; Load the constant 3 into RO 


If you assign a floating-point constant to a symbol, then the symbol can be 
used only as a floating-point constant. Similarly, if you assign an integer con- 
stant to a symbol, then the symbol can be used only as an integer constant. 
The following example is illegal: 


sym -set 3 , Integer constant 
LDF sym, RO ; Invalid — floating-point 
; constant required 


You can also use the .set directive to assign symbolic constants for register 
names. In this case, the symbol becomes a synonym for the register: 


sym -set RO 
LDI 10,sym 


Character Strings 


3.8 Character Strings 


A character string is a string of characters enclosed in double quotes. Double 
quotes that are part of character strings are represented by two consecutive 
double quotes. The maximum length of a string varies and is defined for each 
directive that requires a character string. Characters are represented inter- 
nally as 8-bit ASCII characters. 


These are examples of valid character strings: 
”*sample program” defines a 14-character string, sample program 


”PLAN ””C””” defines an 8-character string, PLAN ”C” 
Character strings are used for the following: 
_j Filenames asin .copy ”"filename” 


Section names asin .sect “section name” 


= 
_j Data initialization directives asin .byte “charstring” 
= 


Operand of .string directive 
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3.9 Symbols 


3.9.1 Labels 


3.9.2 Constants 
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Symbols are used as labels, constants, and substitution symbols. A symbol 
name is a string of up to 32 alphanumeric characters (A—Z, a—z, 0-9, $, and 
_). The first character in a symbol cannot be a number; symbols cannot con- 
tain embedded blanks. The symbols you define are case sensitive; for 
example, the assembler recognizes ABC, Abc, and abc as three unique sym- 
bols. You can override case sensitivity with the —-c assembler option. This type 
of symbol is valid only during the assembly in which it is defined, unless you 
use the .global directive to declare it as an external symbol. 


—_——<“—<— aS a SS ae a <a 


Note: If You Use the —-c Option 


If you use the —c option, the assembler translates all symbols to uppercase. 
If other modules that reference these symbols were not also assembled with 


the —c option, the linker may fail to match global symbols. 
ss 


Symbols that are used as labels become symbolic addresses that are asso- 
ciated with locations in the program. A label used locally within a file must be 
unique. Mnemonic opcodes and assembler directive names (without the ‘.’ 
prefix) are valid label names. 


Labels can also be used as the operand of a .global, .ref, .def, or .bss directive; 
for example, 


-global labell 


label2 nop 
add labell 
b label2 


Symbols can be set to constant values. By using constants, you can equate 
meaningful names with constant values. The .set and .struct/.tag/.endstruct 
directives enable you to set constants to symbolic names. Symbolic constants 
cannot be redefined. The following example shows how these directives can 
be used: 


K .set 1024 
maxbuf .set 2*K 
item sSEruct 
-int value 
-int delta 
i_len .endstruct 
array .tag item 


.-bss array, 


LDI RO, 


i_len*K 


Ne Ne Ne Ne 


array.delta ; 


Symbols 


constant definitions 


item structure definition 
constant offsets value = 0 
constant offsets delta = 1 
constant offset i_len = 2 


array declaration 


arraytl 


The assembler also has several predefined symbolic constants; these are dis- 
cussed in the next section. 


3.9.3 Symbolic Constants 


The assembler has several predefined symbols, including the following: 


LJ 


program counter (SPC). 


Register symbols: 


ARO-AR7 
BK 
DP 


RE 
RC 
RS 


and, for the ’C3x only; 


IF 


IOF 


plus, for the ’C4x only; 


R8-R11 
TVTP 


HE 


(1 $, the dollar sign character, represents the current value of the section 


RO-R7 
SP 
ST 


IIF IVTP 


Version symbols are predefined assembler constants that you can use 
to direct the assembler to produce code for various target processors. Use 
the version symbols with the target version switch or the .version directive. 


Symbols 
.TMS320xx 
.C3X or .C3x 
.C30 

.C31 

.C32 

.C4X or .C4x 
.C40 

.C44 


Value 


30, 31, 32, 40, or 44 


1or0 
1or0 
1or0 
1or0 
toro 
1or0 
1or0 


Description 

set according to -v flag 
1 if -v30, -v31, or -v32 
if -v30 

if -v31 

if -v32 

if -v40 or -v44 

if -v40 

if -v44 


—_ 


ee ee ee eS 
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The following symbols are currently supported, but are obsolete and will 
be removed in a later release: 


Symbols Value Description 
.TMS320C30 1 or0 1 if-v30, -v31, or -v32 
.TMS320C31 1 or0 1 if -v31 

.TMS320C32 1or0 1 if -v32 

.TMS320C40 1 or0 1 if -v40 or -v44 
.TMS320C044 1 or0 1 if -v44 


The .TMS320xx constant is set to the value of the version switch. For 
example, if the assembler is invoked with the following command 
asm30 -v30 filename 

then .TMS320xx equals 30. 

You can use the version symbols to direct the assembler to produce code 
for specific target devices. For example, the following code can produce 
code for differing target devices, depending on how you invoked the as- 
sembler. 

if .TMS320xx = 30 


-endif 
Eco 


.endif 
(1 C Compiler Model Symbols are predefined assembler constants corre- 


sponding to the code generation model of the C compiler. You can use 
these to vary the source code to correctly interface to C code. 


Symbols Value Description 
.REGPARM 1or0 1 if —mr option used 
.BIGMODEL 1or0 1 if -mb option used 


3.9.4 Substitution Symbols 
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Symbols can be assigned a string value (variable). This enables you to alias 
strings of text by equating them to symbolic names. Symbols that represent 
text strings are called substitution symbols. When the assembler encounters 
a substitution symbol, its string value is substituted for the symbol name. Un- 
like symbolic constants, substitution symbols can be redefined. 


A string can be assigned to a substitution symbol anywhere within a program; 
for example, 


-asg "ar3", FP ; frame pointer 
-asg “*-FP(2)”,PARM1 
LDI PARM1, RO ; expands to LDI *-FP(2), RO 


Symbols 


When you are using macros, substitution symbols are important because 
macro parameters are actually substitution symbols that are assigned a macro 
argument. The following code shows how substitution symbols are used in 
macros: 


SUMI -macrosrcl,src2,dest 
LDI srcl,dest 
ADDI src2,dest 
.endm 


invocation: 


SUMI @a, @b, R4 


For more information about macros, refer to Chapter 6. 
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3.10 Expressions 


An expression is an integer or floating-point constant, a symbol equated to an 
integer or floating-point value, or a series of constants and symbols separated 
by arithmetic operators. The range of valid expression values is 
~2,147,483,647 to 4,294,967,295 (-(231-1) to (232-1)). 


Three factors influence the order of expression evaluation: 


Parentheses Expressions that are enclosed in parentheses are 
always evaluated first. 


Example: 8/(4/2) = 4, but 8/4/2 = 1 


Note that you cannot substitute braces ( { } ) or 
brackets ([] ) for parentheses. 


Precedence groups Operators (listed in Table 3-1) are divided into 
four precedence groups. When the order of ex- 
pression evaluation is not determined by paren- 
theses, the highest-precedence operation is 
evaluated first. 


Example: 8 + 4/2 = 10 (4/2 is evaluated first) 


Left-to-right evaluation Whenparentheses and precedence groups do not 
determine the order of expression evaluation, the 
expressions are evaluated from left to right; note 
that the highest precedence group is evaluated 
from right to left. 


Example: 8/4*2 = 4, but 8/(4*2) = 1 


3.10.1 Floating-Point Expressions 


A floating-point constant is a string of decimal digits, followed by a decimal 
point, a fractional portion, and an exponent portion. 


The syntax for a floating-point constant is as follows: 
[ +/-] nnn.nnn[ Eje [ +/—] nnn] 
nnn is a string of decimal digits. 


Floating-point constants may be preceded by a + or a—sign; + is the default. 
Floating-point constants may be assigned to symbols with the .set directive. 
Symbols equated to floating-point values may be used freely in place of 
floating-point constants. 


Expressions 


A floating-point expression is an expression with at least one floating-point 
value in it. You can use a floating-point expression as an operand for the .set, 
.float, and .double directives, and for any instruction that expects a floating- 
point value as an operand. Integer values used in floating-point expressions 
are converted to floating-point values automatically by the assembler. If you 
use a floating-point expression in an instruction that expects an integer value, 
the assembler will generate an error. You cannot use bitwise operators in 
floating-point expressions. Floating-point expressions can be converted to 
Integers using one of the conversion functions. 


Here are some examples of legal floating-point expressions: 


Examples 
fltl -set 1.23 


This example attaches the constant 1.23 to the symbol flt1. This symbol 
can be used in another floating-point expression: 


f1lt2 s£loat'6.57 -= £Lel 


After this example is executed, flt2 is the symbolic address of the value 
5.34 in memory. 


3.10.2 Floating-Point to Integer Conversions 


The assembler provides four built-in functions which round floating-point 
values to integer values: 


$trunc returns the result of the expression rounded towards zero. 
$round returns the result of the expression rounded to the nearest integer. 
$floor returns the largest integer that is not greater than the expression. 


$ceil returns the smallest integer that is not less than the expression. 


Each function returns a signed integer value. Here are some examples that 
use floating-point to integer conversions: 
Examples 


fltl .set 123 
f1t2 -set 3.45/f1t1 
flt3 .set £f1t2 * Sceil(flt1) 


This example attaches a value roughly equal to 5.61 to flt3. 
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3.10.3 Operators 


Table 3—1. Operators 


Table 3-1 lists the operators that can be used in expressions. They are listed 


according to precedence group. 


Group 1 (Highest Precedence) 
Right-to-Left Evaluation 


Unary plus (positive expression) 
Unary minus (negative expression) 


Group 3 
Left-to-Right Evaluation 


Addition 
Subtraction 


Bitwise exclusive-OR 
Bitwise OR 

Bitwise AND 

Logical OR 
Logical AND 


1s complement 


Group 2 
Left-to-Right Evaluation 


Group 4 (Relational Opera- 
tors) Left-to-Right Evaluation 


i Multiplication Less than 

/ Division Greater than 

% Modulo Less than or equal to 
<< | Left shift Greater than to equal to 
>> | Right shift (==) Equal to 


Not equal to 


Notes: 1) Operators within parentheses () indicate an alternate form. 


2) Bitwise operations on floating-point constants will cause an error 


3.10.4 Expression Overflow or Underflow 


3.10.5 Well-Defined 
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The assembler checks for overflow and underflow conditions when arithmetic 
operations are performed at assembly time. The assembler will issue a Value 
Truncated warning whenever an overflow or underflow occurs. The assembler 
does not check for overflow or underflow in multiplication. 


Expressions 


Some assembler directives require well-defined expressions as operands. 
Well-defined expressions contain only symbols or assembly-time constants 
that are defined before they are encountered in the expression. The evaluation 
of a well-defined expression must be absolute. This is an example of a well- 
defined expression: 


1000h+X X has been previously defined as an absolute symbol. 


Expressions 


3.10.6 Conditional Expressions 


The assembler supports relational operators that can be used in any expres- 
sion; they are especially useful for conditional assembly. Relational operators 
include the following: 


>= Greater than or equal to '= Not equal to 
== Equal < Less than 
<= Less than or equal to > Greater than 


These operations have the lowest precedence; however, each has the same 
precedence within the group, so they are evaluated left to right. Conditional 
expressions evaluate to 1 if true and 0 if false. 


3.10.7 Relocatable Symbols and Legal Expressions 


Table 3—2 summarizes valid operations on absolute, relocatable, and external 
symbols. An expression cannot multiply or divide by a relocatable or external 
symbol. An expression cannot contain unresolved symbols that are 
relocatable with respect to different sections. 


Table 3-2. Expressions With Absolute and Relocatable Symbols 


If Ais... and B is... A+B is... A-B is... 
absolute absolute absolute absolute 
absolute external external illegal 
absolute relocatable relocatable illegal 
relocatable absolute relocatable relocatable 
relocatable relocatable illegal absolute T 
relocatable external illegal illegal 
external absolute external external 
external relocatable illegal illegal 
external external illegal illegal 


tA and B must be in the same section; otherwise, this is illegal. 


Here are some examples of expressions that use relocatable and absolute 
symbols. These examples use four symbols that are defined as follows: 


-global extern_1 ;Defined in an external module 


intern_1: -word 1234 ;Relocatable, defined in current module 
LABI1: -set 2 ; absolute 
intern_2: ;Relocatable, defined in current module 
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Example 1 


The statements in this example use an absolute symbol, LAB1. The first 
statement puts the value 51 into register RO, the second statement puts 
the value 8033h in RO, and the third puts 27 in memory address 8033h. 


DI ABl + ((4+3) * 7), ARO ; ARO = 51 
DI AB1l + 4 + 3 * 7, ARO ; ARO = 27 
Example 2 


All legal expressions can be reduced to one of two forms: 
relocatable symbol + absolute symbol 
or 
absolute value 


Unary operators can be applied only to absolute values; they cannot be 
applied to relocatable symbols. Expressions that cannot be reduced to 
contain only one relocatable symbol are illegal. The first statement in the 
following example is legal; the statements that follow it are invalid. 


LDI extern_1 - 10, ARO ;Legal 

LDI 10-extern_1l, ARO 7Can’t negate reloc. symbol 
LDI -—(intern_1), ARO 7;Can’t negate reloc. symbol 
LDI extern_1/10, ARO ;/isn’t an additive operator 
LDI intern_1l + extern_l, ARO ; Multiple relocatables 


Example 3 


The first statement below is legal; although intern_1 and intern_2 are 
relocatable, their difference is absolute because they’re in the same 
section. Subtracting one relocatable symbol from another reduces the 
expression to absolute value + relocatable symbol which is relocatable. 
The second statement is illegal because the sum of two relocatable 
symbols is not an absolute value. 


LDI intern_1l - intern_2 + extern_1,ARO ; Legal 
LDI intern_1 + intern_2 + extern_1,ARO ; Illegal 
Example 4 


An external symbol’s placement in an expression is important to expres- 
sion evaluation. Although the statement below is similar to the first 
statement in the previous example, it is illegal. This is because of left-to- 
right operator precedence; the assembler attempts to add intern_1 to 
extern_1. 


LDI intern_1l + extern_2 - intern_2, ARO ; Illegal 


Source Listings 


3.11 Source Listings 


A source listing shows source statements and the object code they produce. 
To obtain a listing file, invoke the assembler with the —| (lowercase “L”) option. 


At the top of each source listing page are two banner lines, a blank line, and 
a title line. Any title supplied by a .title directive is printed on this line; a page 
number is printed to the right of the title. If you don’t use the .title directive, the 
title area is left blank. The assembler inserts a blank line below the title line. 


Each line in the source file may produce a line in the listing file that shows a 
source statement number, an SPC value, the object code assembled, and the 
source statement. A source statement may produce more than one word of 
object code. The assembler lists the SPC value and object code on a separate 
line for each additional word. Each additional line is listed immediately follow- 
ing the source statement line. 


Field 1 Source Statement Number 
Line Number 


The source statement number is a decimal number. The assembler 
numbers source lines as it encounters them in the source file; some 
statements increment the line counter but are not listed (for exam- 
ple, .title statements and statements following a .nolist are not 
listed). The difference between two consecutive source line num- 
bers indicates the number of statements in the source file that are 
not listed. 


Include File Letter 


The assembler may precede a line with a letter; the letter indicates 
that the line is assembled from an include file. 


Nesting Level Number 

The assembler may precede a line with a number; the number indi- 

cates the nesting level of macro expansions and loop blocks. 
Field 2 Section Program Counter 


This field contains the section program counter, or SPC, value 
(hexadecimal). Each section (.text, .data, .oss, and named sec- 
tions) maintains a separate SPC. Some directives do not affect the 
SPC; they leave this field blank. 
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Field 3 


Field 4 


Object Code 


This field contains the hexadecimal representation of the object 
code. All machine instructions and directives use this field to list 
object code. This field also indicates the relocation type by append- 
ing one of the following characters to the end of the field: 


! undefined external reference .text relocatable 


Mm 


.data relocatable + sect relocatable 
-—  .bss, .usect relocatable A -asect relocatable 


Source Statement Field 


This field contains the characters of the source statement as they 
were scanned by the assembler. The assembler accepts a 
maximum line length of 200 characters. Spacing in this field is de- 
termined by the spacing in the source statement. 


Example 3-1 shows an example of an assembler listing with each of the four 
fields identified. 


Example 3-1. An Assembler Listing 


2 
3 
4 
5 
6 
7 
8 
9 
LO 
Ll 
12 
13 
L4 
L5 
16 
L7 
18 00000000 
19 00000000 
20 


21 00000001 
22 00000002 
23 00000003 
24 00000004 
25 00000005 


27 00000006 
28 00000007 
29 00000008 


Kt Ly 
Field 1 Field 2 


Copyright (c) 


TMS320C3x/4x COFF Assembler Version x.xx Wed Jan 22 10:59:27 1997 
1987-1997 Texas Instruments Incorporated 
PAGE 1 
KKKKKKKKKKKKKKKKK KKK KKK KKK KKK KKK KKK KKK KK KKKKKKKKKKKKKKK 
* TMS320C30 32x32 Integer Multiply x 
* * 
* Inputs: x in RO, y in R1 * 
* ARO points to 2 words of temporary memory * 
* * 
* Outputs: x * y in RO * 
* * 
* Operation: 3 
* Let x0 = 8 MSBs of x, yO = 8 MSBs of y * 
* * 
‘a result = (x0 * y) + (yO * x) + xy * 
KKKKKKKKKKKKKKKKKKKKKKKKKKK KK KKK KKK KKKKKKKKKKKKKKKKKKKK 
-global mpy32 

mpy32: 

C20100C0 STI RO, *ARO ; save x 
| | STI R1, *+ARO ; save y 

O3EOFFE8 ASH —24,R0 ; x0 into RO 

O3E1FFE8 ASH -24,R1 ; yO into R1 

OACO0001 MPYI *+ARO, RO 7 mpy upper bytes: x0 * y 

0AC1C000 MPYI *ARO,R1 ; yO * x 

880800C0 MPYI *ARO,*+ARO,RO ; mpy lower words 
|| ADDI RO,R1,R2 ; add product MSBs 

03E20018 ASH 24,R2 ; shift back to top of word 

02000002 ADDI R2,RO ; add to LSBs 

78800000 RETS 

-end 
Field 3 Field 4 
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3.12 Cross-Reference Listings 


A cross-reference listing shows symbols and their definitions. To obtain a 
cross-reference listing, invoke the assembler with the —x option or use the 
.option directive. The assembler will append the cross-reference to the end of 
the source listing. 


Example 3-2. An Assembler Cross-Reference Listing 


TMS320C3x/4x COFF Assembler Version x.xx Wed Jan 22 10:59:27 1997 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
PAGE 3 
LABEL VALUE DEFN REF 
K16 OOO0OAABB 0007 0041 
K24 OOAABBCC 0008 0049 
K32 AABBCCDD 0009 0057 
K8 OOOO00AA 0006 0071 
KF LOAT E5541885 0010 0065 
ext REF 0011 0026 0034 0042 0050 
0058 0072 
label0 00000002+ 0019 0028 0036 0044 0052 0060 
0074 
labell 00000003’ 0028 0027 0035 0043 0051 0059 
0073 
label column contains each symbol that was defined or referenced 


value 


definition 


reference 


during the assembly. 


column contains a 8-digit hexadecimal number, which is the 
value assigned to the symbol or a name that describes the 
symbol’s attributes. A value may also be followed by a character 
that describes the symbol’s attributes. Table 3-3 lists these 
characters and names. 


(DEFN) column contains the statement number that defines the 
symbol. This column is blank for undefined symbols. 


(REF) column lists the line numbers of statements that reference 
the symbol. A blank in this column indicates that the symbol was 
never used. 
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Table 3-3. Symbol Attributes 


Character or Name 
REF 


UND 
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Meaning 
External reference (global symbol) 


Undefined 

Symbol defined in a .text section 
Symbol defined in a .data section 
Symbol defined in a .sect section 


Symbol defined in a .bss or .usect section 


Chapter 4 


Assembler Directives 


Assembler directives supply program data and control the assembly process. 
Assembler directives allow you to: 


Assemble code and data into specified sections 
Reserve space in memory for uninitialized variables 
Control the appearance of listings 

Initialize memory 

Assemble conditional blocks 

Define global variables 


Specify libraries that the assembler can obtain macros from 


UoooooC UU 


Examine symbolic debugging information 


This section is divided into two parts: the first part (Sections 4.1 through 4.9) 
describes the directives according to function, and the second part 
(Section 4.10) is an alphabetical reference. This section includes: 


Topic Page 
AFD IRECUVES! SUMMARY erecta fete etete fare teteveleteletet fate stetevetetetetststa ce) stenelatetsyer= -2] 
4.2 Directives That Define Sections .............00ceeeee ence eee eee 
4.3 Directives That Initialize Constants .............000eee eee eee eee 4-7 
4.4 Directives That Align the Section Program Counter ............. 4-10 
4.5 Directives That Format the Output Listing ...................... 4-11 
4.6 Directives That Reference Other Files ..............2220200005: 4-13 
4.7 Conditional Assembly Directives .............000ceee seen eee 4-14 
4.8 Assembly-Time Symbol Directives .............00eeeeee seen A-15 
4.9 Miscellaneous Directives ..........0..ccceee eee eec eee eee eeeee 4-16 
410: Directives! Reference: ciciecc ce: cies cte cele ais eels (ainie olclelela aie iclaraieiele lee 4-17 
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4.1 Directives Summary 


Table 4-1 summarizes the assembler directives. All source statements that 
contain a directive may have a label and a comment. To improve readability, 
they are not shown as part of the directive’s syntax. 


Table 4—1. Directives Summary 


Directives That Define Sections 
Mnemonic and Syntax Description 


-asect “section name”, address Assemble into an absolute named (initialized) section (This 


directive is obsolete) 


-bss symbol, size in words [, blocking flag] Reserve size words in the .bss (uninitialized data) section 
-data Assemble into the .data (initialized data) section 

“sect “section name” Assemble into a named (initialized) section 

-text Assemble into the .text (executable code) section 

symbol .usect "section name”, size in words, Reserve size words in a named (uninitialized) section 
[blocking flag] 


Directives That Initialize Constants (Data and Memory) 
Mnemonic and Syntax Description 
-byte value; [, ..., value] Initialize one or more successive bytes in the current section 


Initialize one or more 32-bit, TMS320 single precision, 
floating-point constants 


-double value; [, ..., valueé,] 


-field value [, size in bits] 


float value; [, ... , valuep] 
-hword value; [, ... , valueéy] 
ieee value [, ... , value] 
-int value; [, ... , valuey] 


.ldouble value 


long value; [, ... , valuep] 


-Sfloat value; [, ..., valuey] 


-Space size in bits 
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Initialize a variable-length field 


Initialize one or more 32-bit, TMS320 single precision, 
floating-point constants 


Initialize one or more 16-bit (half-word) values 


Initialize one or more 32-bit, single precision, IEEE floating- 
point constant 


Initialize one or more16-bit integers 


Initialize a 40-bit long double extended precision floating- 
point constant in a compiler supported format 


Initialize one or more 32-bit integers 


(C32 only) Initialize one or more 32-bit, single precision, 
TMS320 floating-point constants 


Reserve size bits in the current section; a label points to the 
beginning of the reserved space 
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Table 4-1. Directives Summary (Continued) 


Mnemonic and Syntax 
String “string,” |, ..., “stringy” 


.word value; [, ... , value,] 


Mnemonic and Syntax 
.align 


even 


Mnemonic and Syntax 


.drlist 

-drnolist 

fclist 

.fcnolist 

length page length 
list 

-mlist 

-mnolist 


nolist 


.option {B/D /F/L/M/T/X} 


.page 
-Sslist 
-ssnolist 
title “string” 


.width page width 


Directives That Initialize Constants (Data and Memory) 


Description 
Initialize one or more text strings 


Initialize one or more 16-bit integers 


Directives That Align the Section Program Counter (SPC) 


Description 
Align the SPC on a page boundary 


Align the SPC on an even word boundary 


Directives That Format the Output Listing 


Description 

Enable listing of all directive lines (default) 

Inhibit listing of certain directive lines 

Allow false conditional code block listing (default) 
Inhibit false conditional code block listing 

Set the page length of the source listing 

Restart the source listing 

Allow macro listings and loop blocks (default) 
Inhibit macro listings and loop blocks 

Stop the source listing 

Select output listing options 

Eject a page in the source listing 

Allow expanded substitution symbol listing 

Inhibit expanded substitution symbol listing (default) 
Print a title in the listing page heading 


Set the page width of the source listing 
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Table 4—1. Directives Summary (Continued) 


Mnemonic and Syntax 
.copy []filename[’ 


-def symbol; [, ... , symbol] 


-global symbol; [, ... , symbol] 


-include [’|filename[] 
-mlib [’}filename[] 


ref symbol; [, ... , symbol] 


Mnemonic and Syntax 


-break [well-defined expression] 


-else 


-elseif well-defined expression 


-endif 
-endloop 
.if well-defined expression 


.loop [well-defined expression] 
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Directives That Reference Other Files 


Description 


Include source statements from another file 


Identify one or more symbols that are defined in the current 
module and used in other modules 


Identify one or more global (external) symbols 
Include source statements from another file 
Define macro library 


Identify one or more symbols that are used in the current mod- 
ule but defined in another module 


Conditional Assembly Directives 


Description 


End .loop assembly if condition is true. The .obreak construct 
is optional. 


Assemble code block if the .if condition is false. The .else 
construct is optional. 


Assemble code block if the .if condition is false and the .elseif 
condition is true. The .elseif construct is optional. 


End .if code block 
End .loop code block 
Assemble code block if the condition is true 


Begin repeatable assembly of a code block 
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Table 4-1. Directives Summary (Concluded) 


Assembly-Time Symbols 


Mnemonic and Syntax 


-asg [’] character string [’|, substitution symbol 
.endstruct 

.eval well-defined expression, substitution symbol 
label ’symbor’ 

set 

-struct 


.tag 


Description 


Assign a character string to a substitution symbol 
End structure definition 

Perform arithmetic on numeric substitution symbols 
Define a load-time relocatable label in a section 
Equate a value with a symbol 

Begin structure definition 


Assign structure attributes to a label 


Miscellaneous Directives 


Mnemonic and Syntax 


.emsg string 

.end 

.mmregs 

-mmsg string 

.regalias 

-version generation #number 


-wmsg string 


Description 


Send user-defined error messages to the output device 
End program 

Enter memory-mapped registers into symbol table 
Send user-defined messages to the output device 

Use Fn registers as aliases for Rn registers 

Set processor version 


Senduser-defined warning messages to the output device 
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4.2 Directives That Define Sections 


Six directives associate the various portions of an assembly language 
program with the appropriate sections: 


L] 
L] 


The .bss directive reserves space in the .bss section for variables. 


The .usect directive reserves space in an uninitialized named section. 
The .usect directive is similar to the .oss directive, but it allows you to re- 
serve space separately from the .bss section. 


The .text directive identifies portions of code in the .text section. The .text 
section usually contains executable code. 


The .data directive identifies portions of code in the .data section. The 
.data section usually contains initialized data. 


The .sect directive defines initialized named sections, and associates 
subsequent code or data with that section. Named sections are initialized 
and contain code or data. 


The .asect directive creates initialized named sections that have absolute 
addresses. You can use the .label directive to define labels with absolute 
addresses. 


Chapter 2 discusses COFF sections in detail. 


Directives That Initialize Constants 


4.3 Directives That Initialize Constants 


Several directives assemble values into the current section: 


L) 


The .byte directive places one or more 8-bit values into consecutive words 
of the current section. This directive is similar to .word, except that the 
width of each value is restricted to 8 bits. 


The .hword directive places one or more 16-bit half-word values into con- 
secutive words in the current section. This directive is similar to .word, ex- 
cept that the width of each value is restricted to 16 bits. 


The .word, .int, and .long directives place one or more 32-bit values into 
consecutive locations in the current section. 


The .string directive places 8-bit characters from one or more character 
strings into the current section. This directive is similar to .byte, except that 
four 8-bit values are packed into each word. The last word in a string is 
padded with null characters (Os) if necessary. 


The .float and .double directives calculate the single-precision (32-bit) 
floating-point representations of specified floating-point values and store 
them in consecutive words in the current section. Here’s an example of a 
float directive and the object code that it generates: 


5 00000003 0274ED91 - float 7.654 


The .ieee directive is like the .float directive, but the floating-point values 
are converted to single-precision IEEE floating-point format. 


The .Idouble directive calculates the extended-precision floating-point 
representation of a long double floating-point constant and stores it into 
two consecutive 32-bit words in the current section. Each constant is con- 
verted to a floating-point value in 40-bit format. 


The .sfloat directive is available only with the -v32 assembler option. The 
.Sfloat directive calculates the single-precision (32-bit) floating-point 
representations of specified floating-point values and stores them in 
consecutive words in the current section. The format is the normal single- 
precision format right shifted by 16 bits. 


Note: How the Initializing Directives Function in a .struct/.endstruct 
Sequence 


The .byte, .word, .int, .long, .string, .float, ieee, .sfloat, and .field directives 
do notinitialize memory when they are part of a .struct/.endstruct sequence; 
rather, they define a member’s size. For more information about the 


.struct/.endstruct directives, refer to Section 4.8. 
eee eee ee ee eee sss | 
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Example 4—1 compares the .byte, .hword, .word, and string directives; for this 
example, assume the following code was assembled: 


1 00000000 000000AB -byte OABh 

2 00000001 OO0O0CDEF -hword OCDEFh 

3 00000002 89ABCDEF .word 089ABCDEFh 
4 00000003 706C6568 -string “help” 


Example 4-1. Initialization Directives 


Word Contents Code 
31 0 
1 0 0 0 0 0 0 A B byte OABh 
—a 
1 byte 
2 0 0 0 0 Cc D E F -hword 
OCDEFh 
2 bytes (half word) 
3 8 9 A B Cc D E F .word 
089ABCDEFh 
eee — OEE, 
whole word 
4 70 6C 65 68 -String 
help 


(1 The .field directive places a single value into a specified number of bits 
in the current word, starting with the least significant bits of the word. You 
can pack multiple fields into a single word; the assembler will not incre- 
ment the SPC until a word is filled. 


Example 4—2 shows how fields are packed into a word. For this example, 
assume the following code has been assembled; notice that the SPC 
doesn’t change (the fields are packed into the same word): 


6 00000004 00000003 .field 3,4 
7 00000004 00000083 »field 8,5 
8 00000004 00002083 . field 16,7 
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Directives That Initialize Constants 


Example 4—2. The .field Directive 


31 3 2 1 0 

| 0 0 1 1 field 3,4 
a, 

31 8 7 4 bits 


| 0 1 0 0 0);0 0 1 1/7] <field 8,5 


31 15 14 13 12 11:10 9 
| 001 00 0 0;/0 10 0 0/0 0 1 #14 field 16,7 


_) The .space directive reserves a specified number of words in the current 
section. The assembler fills these reserved words with Os. 


Example 4—3 shows the .space directive; assume the following code has 
been assembled: 


154 0000027A080F000C LDI AR4,AR7 


155 0000027B 00000000 .space 27 
156 00000296 OOOOO000F .word 15 


Example 4—3. The .space Directive 


LDI AR4, AR7 LDI AR4, AR7 


27 
(a) Current 


SPC 27Ah 


v 


(b) New SPC = 296h 
after assembling a 
Space 27 directive 
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4.4 Directives That Align the Section Program Counter 


(1 The.align directive aligns the SPC on a 32-word (20 hex) boundary. This 
ensures that the code following the .align directive begins on a cache 
boundary. If the SPC is already aligned at a 32-word boundary, then it is 
not incremented and .align has no effect. Example 4—4 shows the .align 
directive; assume that the following code has been assembled: 


202 00000C11 00000004 -byte 4 
201 00000C11 00000000 -align 
203 00000C20 00000003 -byte 3 


Example 4-4. The .align Directive 


(a) Current oCith OCtth —(b) New SPC = 0C20h 

SPC = 0C1th after assembling an 

.align directive 

(b) next cache 0C20h 0C20h Oe 

boundary = 

0C20h eae os, 

Z 
ee 4 


(1 The .even directive aligns the SPC so that it points to the next full word. 
You should use .even between field directives when you want the next field 
to start in a new word. Any unused bits in the current word are filled with 
Os. 


Example 4—5 shows the effect of assembling a .even directive after a .field 
directive. Assume the following code has been assembled: 


6 00000004 00000003 .field 3,4 
7 00000004 00000083 .field 8,5 
8 00000005 .even 


Example 4—5. The .even Directive 


31 


0 
0o0000000000000000000000j/010000011 


= 


These bits are filled with Os These bits were filled 
after assembling a .even directive by .field directives 
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4.5 Directives That Format the Output Listing 


Several directives format the listing file: 


Lj 


The source code contains a listing of false conditional blocks that do not 
generate code. The .fclist and .fcnolist directives turn this listing on and 
off. You can use the .fclist directive to list false conditional blocks exactly 
as they appear in the source code. You can use the .fcnolist directive to 
list only the conditional blocks that are actually assembled. 


The .drlist and .drnolist directives turn the printing of directive lines to the 
listing file on and off. You can use the .drnolist directive to inhibit the 
printing of the following directives: 


.asg eval, length .mnolist —.var 
.break fclist .mmsg Sslist, .width 
.emsg cnolist —.mlist ssnolist .wmsg 


The .length directive controls the page length of the listing file. You can 
use this directive to adjust listings for various output devices. 


The .width directive controls the page width of the listing file. You can use 
this directive to adjust listings for various output devices. 


The .list and .nolist directives turn the output listing on and off. You can 
use the .nolist directive to stop the assembler from printing selected 
source statements in the listing file. Use the .list directive to turn the listing 
back on. 


The .mlist and .mnolist directives allow and inhibit macro expansion list- 
ings. 


The .option directive controls several features in the listing file. This direc- 
tive has several operands: 

Limits the listing of .byte directives to one line. 

Limits the listing of .nword directives to one line. 

Resets the B, H, L, M, and T options. 

Limits the listing of .long, .int, and .word directives to one line. 
Limits macro expansions to one line. 


Limits the listing of .string directives to one line. 


<x<HAe2r4mtiow 


Produces a cross-reference listing of symbols. (You can also ob- 
tain across-reference listing by invoking the assembler with the -x 
option.) 


The .page directive causes a page eject in the output listing. 
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Directives That Format the Output Listing 


The .sslist and .ssnolist directives allow and inhibit substitution symbol 
expansion listing. These directives are useful for debugging substitution 
symbols outside of macros. 


The .title directive supplies a title that the assembler prints on the second 
line of each page. 


Directives That Reference Other Files 


4.6 Directives That Reference Other Files 


These directives supply information for or about other files: 


L) 


The .copy and .include directives tell the assembler to begin reading 
source statements from another file. When the assembler is finished read- 
ing the source statements in the copy/include file, it resumes reading 
source statements from the current file. The statements read from a 
copied file are printed in the listing file; the statements read from an in- 
cluded file are not printed in the listing file. 


The .global directive declares a symbol to be external so that itis available 
to other modules atlink time. The .global directive does double duty, acting 
as a .def for defined symbols and as a .ref for undefined symbols. Note that 
the linker will resolve an undefined global symbol only if it is used in the 
program. 


The .def directive identifies a symbol that is defined in the current module 
and can be used by other modules. The assembler puts the symbol in the 
symbol table. 


The .ref directive identifies a symbol that is used in the current module but 
defined in another module. The assembler marks the symbol as an unde- 
fined external symbol and puts it in the object symbol table so that the 
linker can resolve its definition. 


The .mlib directive supplies the assembler with the name of an archive 
library that contains macro definitions. When the assembler encounters 
a macro that is not defined in the current module, it will then be able to 
search for it in the specified macro library. 
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4.7 Conditional Assembly Directives 


Conditional assembly directives enable you to instruct the assembler to 
assemble certain sections of code according to a true or false evaluation of an 
expression. Two sets of directives allow you to assemble conditional blocks of 
code: 


1 The .if/.elseif/.else/.endif directives tell the assembler to conditionally 
assemble a block of code according to the evaluation of an expression. 


.if expression Marks the beginning of a conditional block and 
assembles code if the .if condition is true. 


elseif expression Marks a block of code to be assembled if .if is false 
and .elseif is true. 


.else Marks a block of code to be assembled if .if is false. 
.endif Marks the end of a conditional block and terminates 
the block. 


(1 The .loop/.break/.endloop directives tell the assembler to repeatedly 
assemble a block of code according to the evaluation of an expression. 


-loop expression Marks the beginning a repeatable block of code. 


-break expression Continue to repeatedly assemble when the .break 
expression is false. Go to code immediately after 
.endloop if expression is true. 


-endloop Marks the end of a repeatable block. 
The assembler supports several relational operators that are especially useful 


for conditional expressions. For more information about relational operators, 
refer to Section 3.10 on page 3-20. 


Assembly-Time Symbol Directives 


4.8 Assembly-Time Symbol Directives 


These directives equate meaningful symbol names to constant values or 
strings. 


Lj 


type sSEEUCE 


x 
y 


t_len -endstruct 


The .set directive sets a constant value to asymbol. The symbol is stored 
in the symbol table and cannot be redefined; for example, 
bval -set  0100h 


-word bval, bval*2, bval+12 
LDI bval, RO 


Note that the .set directive produces no object code. 


The .struct/.endstruct directives set up C-like structure definitions, and 
the .tag directive assigns the C-like structure characteristics to a label. 


The .struct/.endstruct directives enable you to set up a C-like structure 
definition so that similar elements can be grouped together. Element offset 
calculation is then left up to the assembler. The .struct/.endstruct direc- 
tives do not allocate memory. They simply create a symbolic template that 
can be used repeatedly. 


The .tag directive assigns structure characteristics to a label. This 
simplifies the symbolic representation and also provides the ability to de- 
fine structures that contain other structures.The .tag directive does not 
allocate memory, and the structure tag (stag) must be defined before it is 
used. 

structure tag definition 

member x offset = 0 


member y offset = 1 
end structure, symbol t_len = 2 


«int 
<int 


Ne Ne Ne Ne 


coord .tag type + associate coord w/ structure type 


i) 


ADDI @coord.y, RO 


-bss coord, t_len ; actual memory allocation 


The .asg directive assigns a text string to a substitution symbol. The value 
is stored in the substitution symbol table. When the assembler encounters 
a substitution symbol, it replaces the symbol with its character string value. 
Substitution symbols can be redefined. 


-asg "10, 20, 30, 40”, coefficients 


-word coefficients 


The .eval directive evaluates an expression, translates the results into a 
text string and assigns the string to a substitution symbol. This directive 
is most useful for manipulating counters; for example, 


.asg 1, x ; assigns “1” to x 
.eval x+1, x ; assigns “2” to x 
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4.9 Miscellaneous Directives 


This section discusses miscellaneous directives. 


a) 


a) 


The .version directive is the same as the —-v assembler option. This tells 
the assembler which generation processor the code is for. Valid 
generation numbers are 30 and 40. The default is 30. The .version direc- 
tive must appear before any other instruction or directive, or else an error 
will occur. 


The .end directive terminates assembly. It should be the last source 
statement of a program. This directive has the same effect as an end-of- 
file. 


The .regalias directive allows Fn registers to be used as aliases for Rn 
registers. 


These three directives enable you to produce your own error and warning 
messages: 


i) 


The .emsg directive sends error messages to the standard output device. 
The .emsg directive generates errors in the same manner as the assem- 
bler does, incrementing the error count and preventing the assembler from 
producing an object file. 


The .wmsg directive sends warning messages to the standard output de- 
vice. The .wmsg directive functions in the same manner as the .emsg 
directive but increments the warning count. 


The .mmsg directive sends assembly-time messages to the standard out- 
put device. The .mmsg directive functions in the same manner as the 
.emsg and .wmsg directives but does not set the error count or the warning 
count, and does not prevent an object file from being produced. 


Directives Reference 


4.10 Directives Reference 


The remainder of this chapter is a reference. Generally, the directives are 
organized alphabetically, one directive per page; however, related directives 
(such as .if/.else/.endif) are presented together on one page. Here’s an alpha- 
betical table of contents for the directives reference: 


Directive Page Directive Page 


.data .mmsg 
.def munolist 

cri newblock 

-nolist 

.drnolist .option 
.else .page 

elseif POP chr ceecneeeencan dene 
emsg .regalias 

.end 

sect 

endloop Ob einai Ae uread aus emer 
endif .Sfloat 

endstruct space 

equ sslist 

eval ssnolist 

even String 

fclist -struct 

fcnolist MAD it cs ehetrilurntod tr athe Oecd eats 
field FC (0 eee eee 
float text 

global title 

-hword usect 

.leee .version 

wif width 

include wmsg 

-int word 
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Description The .align directive aligns the section program counter on the next 32-word 
boundary. If necessary, the assembler inserts words containing NOPs. If more 
than 4 NOPs are inserted, the assembler also inserts a branch instruction 
around the NOPs to the next instruction. This directive is useful for aligning 
code on a cache boundary. 


Using the .align directive has two effects: 


(1 The assembler aligns the SPC on a 32-word boundary within the current 
section. 


(} The assembler sets a flag that forces the linker to align the entire section 
ona32-word boundary. This ensures that individual alignments remain in- 
tact when a section is loaded into memory. 


Example This example aligns the SPC on the next 32-word boundary to ensure that the 
code that follows it will start on a cache boundary. Figure 4—1 shows how this 
code aligns the SPC. 


1 00000000 08010000 LDI RO,R1 
2 -align 

3 00000020 08020001 x: LDI R1,R2 

4 00000021 08030002 LDI R2,R3 


Figure 4-1. The .align Directive 


LDI RO, R1 
B 20 
NOP 

NOP 


(a) Current 
SPC = 0h 


(b) next cache 
boundary = LDI R1, R2 
20h LDI R2, R3 

| 


| 
(a) LDI RO, R1 (b) .align 


LDI R2, R3 


Syntax 


Description 


sasect section name”, address 


The .asect directive defines a named section whose addresses are absolute 
with respect to address. This command is obsolete. Any section can now be 
loaded and run at two separate addresses using the linker. The command 
functions as before for compatibility. 


sectionname a required parameter that identifies the name of the 
absolute section. It be enclosed in double quotes. 


address a required parameter that identifies the section’s absolute 
starting address in target memory, which is required the first 
time you assemble into a specific absolute section. If you 
use .asect to continue an assembly into an a section that 
contains code, you cannot use the address parameter. 


Absolute sections are useful for loading sections of code from off-chip memory 
into faster on-chip memory. In order to use an absolute section, you must know 
which location you want the section to execute from and specify it as the 
address parameter. 


Most sections directives create sections with relocatable addresses. The 
starting SPC value for these sections is always zero; the linker then relocates 
them where appropriate. The starting SPC value for an absolute section, 
however, is the specified address. The addresses of all code assembled into 
an absolute section are offsets from the specified address. The linker does 
relocate sections defined with .asect; however, any labels defined within an 
absolute section retain their absolute (runtime) addresses. Thus, references 
to these labels refer to their runtime addresses, even though the section is not 
initially loaded at its runtime address. 


All labels in an absolute section have absolute addresses. The .label directive 
creates /abels with relocatable addresses; this allows you to define a symbol 
that points to the section’s loadtime location in off-chip memory. 


Note that after you define a section with .asect, you can use the .sect directive 
later in the program to continue assembling code into the absolute section. 


ee — — — Fe il 


Note: The .asect Directive Is Obsolete 


The .asect directive is obsolete because the linker’s SECTIONS directive 
now allows separate load and run addresses for any section. The .asect 
directive is fully functional to allow compatibility with previous versions of the 


assembler. For more information, refer to Section 8.7 on page 8-27. 
| es) 
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Syntax 


Description 


-asg [” character string[”’], substitution symbol 
eval well-defined expression, substitution symbol 


The .asg directive assigns character strings to substitution symbols. Substitu- 
tion symbols are stored in the substitution symbol table. 


The .asg directive can be used in many of the same ways as the .set directive, 
but while .set assigns a constant value (cannot be redefined) to a symbol, .asg 
assigns a string (can be redefined) to a substitution symbol. 


The .eval directive performs arithmetic on substitution symbols. This directive 
evaluates the expression and assigns the string value of the result to the sub- 
stitution symbol. The .eval directive is especially useful as a counter in 
.loop/.endloop blocks. 


character string Is assigned to the substitution symbol by the 
assembler. The quotation marks are optional. If 
there are no quotation marks, the assembler 
reads characters up to the first comma and 
removes leading and trailing blanks. In either 
case, a character string is read and assigned to 
the substitution symbol. 


substitution symbol Is arequired parameter that must be a valid sym- 
bol name. The substitution symbol may be 32 
characters long and must begin with a letter. 
Remaining characters of the symbol can be a 
combination of alphanumeric characters, under- 
scores, and dollar signs. When the assembler 
encounters a substitution symbol in a source 
statement, it substitutes the assigned string for 
the symbol and rescans the line. In this way, sub- 
stitution symbols provide a general text replace- 
ment mechanism. 


well-defined expression |s an alphanumeric expression consisting of 
legal values that have been previously defined, 
so that the result is an absolute. 


Example 


This example shows how .asg and .eval can be used. 


1 
2 
3 
4 


5 
6 
7 
8 
9 
0 
1 


1 
1 


00000000 


00000001 


00000002 


00000003 


00000004 


00000005 


00000006 


02400302 


02400301 


00000001 


00000002 


00000003 


00000004 


00000005 


-ssli 
.asg 
.asg 
ADDI 
ADDI 
ADDI 


.asg 
. loop 
-eval 
.word 
.endl 
.eval 


st 
AR3, FP 
RO, TEMP 
*+FP (2), 
*+AR3 (2), 
*+AR3 (1), 
0,x 
5 
x1, 
x 
oop 
oly. 
O+1, x 
x 
1 
xt+1, x 
1+1, x 
x 
2 
xi Ly, 
2+1, x 
x 
3 
xt+1, x 
3+1, xX 
x 
4 
xt+1, x 
4+1, x 
x 
5 


TEMP 
RO 
RO 
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Syntax 


Description 


Example 


PRPPPRPRPRE 
YDUBWNFPOCODRIHDUGUAWNE 
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00000000 
00000000 08010000 


00000000 


00000001 08020001 


-bss symbol, size in words 


The .bss directive reserves space in the .bss section for variables. This direc- 
tive is usually used to allocate variables in RAM. 


symbol Is a required parameter. It defines a label that points 
to the first location reserved by the directive. The sym- 
bol name should correspond to the variable that you’re 
reserving space for. 


size in words Is a required parameter; it must be an absolute 
expression. The assembler allocates size words in the 
.Oss section. There is no default size. 


Note that the .usect directive is similar to the .bss directive; it also reserves 
space in memory. However, .usect creates named uninitialized sections that 
can be allocated separately from the .bss section. 


Other section directives (.text, .data, .sect, and .asect) end the current section 
and begin assembling into another section. The .bss directive, however, does 
not affect the current section. The assembler assembles the .bss directive and 
then resumes assembling code into the current section. For more information 
about COFF sections, see Chapter 2. 


This example uses the .bss directive to allocate space for the variable array. 
The symbol array points to 100 words of uninitialized space (the .bss SPC = 
0). Note that symbols declared with the .bss directive can be referenced in the 
same manner as other symbols and can also be declared external. 


KKK KK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KK 


* Begin assembling into .text ae 
KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KK KKKKK KK 
-text 
LDI RO,R1 
KKK KKK KKK KEK KKK KKK KKK KKK KKKKKKKK KKK KKK KK KK 
* Allocate 100 words in .bss x 
KKK KK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKK 
.bss array,100 
KEKE KK KKK KK KKK KKK KKK KKK KKKKKKKKKK KKK KKK KK 
* Still in .text * 
KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK 
LDI R1,R2 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 


* Declare external .bss symbol i 
KEK KKK KKK KKK KKK KEKE KKK KKK KKK KEKKKKKKKKKKKKEKK 


-global array 


Syntax 


Description 


Example 


-byte value; [, ..., value,] 


The .byte directive places one or more 8-bit values into consecutive words in 
the current section. Each value can be either: 


_j Anexpression that the assembler evaluates and treats as an 8-bit signed 
number, or 


.) Acharacter string enclosed in double quotes. Each character represents 
a separate value. 


Values are not packed or sign extended; each byte value occupies the least 
significant 8 bits of a full 32-bit word. The assembler truncates values that are 
greater than 8 bits. You can define up to 100 values per .byte instruction, how- 
ever, the line length, including label (if any), the .byte directive itself and all val- 
ues, cannot exceed 200 characters. Each character in a string is counted as 
a separate operand. 


If you use a label, it points to the location at which the assembler places the 
first byte. 


This example places the 8-bit values 10, —1, abc and a into four consecutive 
words in memory. The label sirx has the value 64h, which is the location of the 
first initialized word. 


1 
2 00000064 OOOO0000A strx: -byte 10,-1,”abc”,’a’ 
00000065 OOOOO0FF 
00000066 00000061 
00000067 00000062 
00000068 00000063 
00000069 00000061 
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Syntax 


Description 


Example 1 


-copy ["]filename[”] 
include [”]filename[”’] 


The .copy and .include directives tell the assembler to read source statements 
from a different file. The statements that are assembled from a copy file are 
printed in the assembly listing. The statements that are assembled from an in- 
cluded file are not printed in the assembly listing, regardless of the number of 
.list/.nolist directives that are assembled. The assembler: 


1) Stops assembling statements in the current source file, 
2) Assembles the statements in the copied/included file, and 


3) Resumes assembling statements in the main source file, starting with the 
statement that follows the .copy or .include directive. 


The filename is a required parameter that names a source file; the filename 
may be enclosed in double quotes. The filename must follow operating system 
conventions. You can specify a full pathname (for example, .copy 
c:\dsp\file1.asm). If you do not specify a full pathname, the assembler 
searches for the file in: 


1) The directory that contains the current source file. 
2) Any directories named with the -i assembler option. 
3) Any directories specified by the environment variable A_DIR. 


For more information about the -i option and the environment variable, see 
Section 3.5, Naming Alternate Directories for Assembler Input, on page 3-7. 


The .copy and .include directives may be nested within a file being copied or 
included. The assembler limits this type of nesting to ten levels; the host oper- 
ating system may set additional restrictions. The assembler precedes the line 
numbers of copied files with a letter code to identify the level of copying. An 
A indicates the first copied file, B indicates a second copied file, etc. 


This example uses the .copy directive to read and assemble source state- 
ments from other files, then resumes assembling into the current file. 


The original file, copy.asm, contains a .copy statement copying the file 
byte.asm. When copy.asm assembles, the assembler copies byte.asm into its 
place in the listing (note listing below). The copy file byte.asm contains a .copy 
statement for a second file, word.asm. 


When it encounters the .copy statement for word.asm, the assembler switches 
to word.asm to continue copying and assembling. Then the assembler returns 
to its place in byte.asm to continue copying and assembling. After completing 
assembly of byte.asm, the assembler returns to copy.asm to assemble its 
remaining statement. 


copy.asm byte.asm 
.space 29 
.copy byte.asm 
** Back in copy.asm 
-string “done” 


. copy 


** In byte.asm 
-byte 32,1+/A’ 
"“word.asm” 
** Back in byte.asm 


-byte 67h + 3q 


This is the listing file: 


word.asm 


**x In word.asm 


-word OABCDh, 56q 


-space 29 

-copy byte.asm 
In byte.asm 

-byte 32,1+’A’ 

-copy “word.asm” 
In word.asm 

-word OABCDh, 56q 
Back in byte.asm 

-byte 67h + 3q 
Back in copy.asm 

.string “done” 


This example uses the .include directive to read and assemble source state- 


ments from other files, then resumes assembling into the current file. 


1 00000000 00000000 
2 
A 1 
A 2 0000001d 00000020 
0000001le 00000042 
A 3 
B 1 
B 2 0000001f O000abcd 
00000020 0000002e 
A 4 
A 5 00000021 0000006a 
3 
4 00000022 656e6f64 
Example 2 
include.asm byte2.asm 
-space 29 ** In byte2.asm 


-include byte2.asm 
** Back in include.asm 
-string “done” 


.- include 


-byte 32,1+/A’ 
"word2.asm” 
** Back in byte2.asm 


-byte 67h + 3q 


This is the listing file: 
1 00000000 
2 
3 
4 00000022 


00000000 


656e6f64 


word2.asm 


** In word2.asm 


-word OABCDh, 56q 


-Sspace 29 

-include byte2.asm 
** Back in include.asm 

.string “done” 
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Syntax .data 


Description The .data directive tells the assembler to begin assembling source code into 
the .data section; .data becomes the current section. The .data section is nor- 
mally used to contain tables of data or preinitialized variables. 


Chapter 2 provides a detailed explanation about COFF sections. 


Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the .text 
section unless you specify an explicit section control directive. 


Example This example assembles code into the .data and .text sections. 
‘iL. KKK KKK KKK KKK KKK KKK KKK KKK KEK KKK KKEKKKEKKKEK 
2 x** Reserve space in .data =e 
3 KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKKKKEK 
4 00000000 .data 
5 00000000 00000000 -space OCCh 
6 KEK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKEK 
7 ae Assemble into .text ae 
8 KKK K KK KKK KKK KKK KKK KKKKKKKKKKK KKK KKK KKK 
9 00000000 -text 
10 00000000 00800000 ABSI RO 
Li KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKEK 
12 a Assemble into .data ae 
13 KKK KKK KKK KKK KKK KK KKKKKKKKKKKKKKKKKKKKK 
14 000000cc table: -data 
15 000000cc fffffffFf .word =a) ; Assemble 32-bit 
; constant into .data 
16 000000cd OO00000fFE .byte OFFh ; Assemble 8-bit 
; constant into .data 
17 000000ce 08010000 LDI RO,R1l ; Assemble code into .data 
18 KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKEKKK KKK 
19 eX Assemble into .text td 
20 KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKKKKK 
21 00000001 -text 
22 00000001 08010000 LDI RO,R1 
23 KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKKKKK 
24 EX Resume assembling into .data** 
25 iit at address OCFh eas 
26 KKK KKK KKK KKK KKK KK KKK KKK KKK KKKKKKKKKKKEK 
27 000000cf .data 
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Syntax 


Description 


Example 


.drlist 
.drnolist 


The .drlist directive causes the assembler to print to the listing file all directives 
lines. By default the assembler behaves as if you had used .drlist. The .drnolist 
directive suppress the printing of the followings directives in the listing file: 


.asg fclist .mmsg .var 
break fcnolist .mnolist .wmsg 
.emsg length .Sslist .width 
eval .mlist .ssnolist 


This example shows how .drnolist inhibits the listing of the above named direc- 
tives. By default, the assembler behaves as if you had used .drlist. 


Source file: 

* 

% .drlist/.drnolist example 

* 
-length 65 
-width 85 
.asg 0, x 
. Loop 2 
-eval sed yo 
.endloop 
.drnolist 
-length 55 
-width 95 
.asg Liye 3 
. Loop 3 
.eval xy eX 
.endloop 
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Listing file: 


* 


1 
2 
.drlist/.drnolist example 


-length 
.width 
.asg 

. loop 
.eval 
.endloop 
.eval 
-eval 


. Loop 
.eval 
.endloop 


65 
85 
QO, x 
2 
xt+1, 
O+1, 
1+1, 
3 
x1, 


Syntax 


Description 


Example 


.emsg string 
-mmsg string 
-wmsg string 


Use these directives to produce your own error and warning messages. Note 
that the assembler tracks the number of errors and warnings it encounters and 
prints these numbers on the last line of the listing file. 


Lj 


The .emsg directive sends error messages to the standard output device. 
The .emsg directive generates errors in the same manner as the assem- 
bler does, incrementing the error count and preventing the assembler from 
producing an object file. 


The .wmsg directive sends warning messages to the standard output de- 
vice. The .wmsg directive functions in the same manner as the .emsg 
directive but increments the warning count. 


The .mmsg directive sends assembly-time messages to the standard out- 
put device. The .mmsg directive functions in the same manner as the 
.emsg and .wmsg directives but does not set the error count or the warning 
count, and does not prevent the assembler from producing an object file. 


Inthis example, the macro MSG_EX requires one parameter. The first time the 
macro is invoked it has a parameter, PARAM, and it assembles normally. The 
second time, the parameter is missing and an error is generated. 


Source file: 


MSG_EX -macro a 


at Ssymlen(a) = 0 

-emsg "ERROR —- MISSING PARAMETER” 
.else 

ADDI @a, R4 

.endif 

.endm 


-global param 
MSG_EX param 


MSG_EX 
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Listing file: 


1 MSG_EX -macro a 
2 sit Ssymlen(a) = 0 
3 -emsg "ERROR -—- MISSING PARAMETER” 
4 .else 
5 ADDI @a, R4 
6 .endif 
7 .endm 
8 
9 -global param 
10 00000000 MSG_EX param 
It -if Ssymlen(a) = 0 
Al -emsg ”ERROR -- MISSING PARAMETER” 
1 .else 
1 00000000 02240000! ADDI @param, R4 
Hi .endif 
11 
12 00000001 MSG_EX 
‘i. eit Ssymlen(a) = 0 
1 -emsg ”ERROR -- MISSING PARAMETER” 
xxkkk*KK**K USER ERROR - ERROR --— MISSING PARAMETER 
al .else 
1 ADDI @a, R4 
1 .endif 
13 
1 Error, No Warnings 
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The following message is sent to standard output when the file is assembled: 


"emsg.asm” line 12: ** USER ERROR ** 
ERROR -- MISSING PARAMETER 


1 Error, No Warnings 


Errors in source —- Assembler Aborted 


Syntax 


Description 


Example 


.end 


The .end directive is an optional directive that terminates assembly. It should 
be the last source statement of a program. The assembler will ignore any 
source statements that follow an .end directive. 


Note that this directive has the same effect as an end-of-file. 


a | 


Note: Use .endm to End a Macro 


Do not use the .end directive to terminate a macro; use the .endm macro 
directive instead. 


eee sss) 


This example shows how the .end directive terminates assembly. If any source 
statements follow the .end directive, the assembler ignores them. 


1 0000 Start: .space 300 

2 OOOF temp .set 15 

3. 0000 -bss locl, 48h 
4 0013 CEI1B ABS 

5 0014 OOOF ADD temp 

6 0015 6000 SACL locl 

7 .end 
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Syntax 


Description 


Example 


1 
2 
3 
4 


00000000 00000003 
00000000 0000002£ 
00000001 

00000001 00000007 


-even 


The .even directive aligns the section program counter (SPC) on the next full 
word. When you use the .field directive, you can follow it with the .even direc- 
tive. This forces the assembler to write out a partially filled word before initializ- 
ing fields in the next word. The assembler will fill the unused bits with Os. If the 
SPC is already on a word boundary (no word is partially filled), .even has no 
effect. 


All directives that initialize memory other than .field (Such as .word and .float) 
perform an implicit .even. Therefore, it is necessary to use .even only after a 
field directive, and only when word alignment is required for another immedi- 
ately following .field directive. 


Note that when you use .even in a .struct/.endstruct sequence, .even aligns 
structure members; it does not initialize memory. For more information about 
.struct/.endstruct, refer to Section 4.8. 


Here’s an example of the .even directive. Word 0 is initialized with several 
fields; the .even directive causes the next field to be placed in word 1. 


-field O3h,2 ; Initialize a 2-bit field 
.-field OBh, 5 ; Initialize a 5-bit field 
.even ; Write out the word 

.field O7h,3 ; field is in the next word 


Example 4—6 shows how this example initializes word 0. The first 7 bits are in- 
itialized by .field directives; the remaining bits are set to 0 by the .even direc- 
tive. The next 3-bit .field goes into word 1. 


Example 4-6. The .even Directive 


15 0 
| oo | GAIA nO me NOMOM OM ONIN 
be al oO 
ruled by Filled by the field directives 

the .even 

directive 


Syntax fclist 
.fcnolist 


Description Two directives enable you to control the listing of false conditional blocks. 


(1 The .fclist directive allows the listing of conditional blocks that do not pro- 
duce code (false blocks). By default, the assembler behaves as if you had 
used .fclist. 


) The .fcnolist directive inhibits the listing of false conditional blocks. Only 
code in the conditional block that actually assembles appears in the listing. 
The .if, .elseif, .else, and .endif directives do not appear. 


Example This example shows the assembly language file and the listing file for code 
with and without the conditional blocks listed. This is the unassembled file: 
Source file: 
a .set ‘. 
b .set 0 
.fclist ; list false 
; conditional blocks 
ert a 
ADDI 5, RO 
.else 
ADDI 5*10, RO 
endif 
.fcnolist ; do not list 
sate a 
ADDI 5, RO 
.else 
ADDI 5*10, RO 
endif 
Listing file: 
Al 00000001 a .set 1 
2 00000000 b .set 0 
3 stelist ; list false 
4 ; conditional blocks 
5 
6 Lt a 
7 00000000 02600005 ADDI 5, RO 
8 .else 
9 ADDI 5*10, RO 
10 endif 
11 
12 -fcnolist ; do not list 
13 
15 00000001 02600005 ADDI 5, RO 
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Syntax 


Description 


field value [, size in bits] 


The .field directive initializes multiple-bit fields within a single word of memory. 
This directive has two operands: 


_j The valueis arequired parameter; it is an expression that is evaluated and 
placed in the field. If the value is relocatable, size must be 32. 


1 The size is an optional parameter; it specifies a number from 1-32, which 
is the number of bits the field consists of. If you do not specify a size, the 
assembler uses a default size of 32 bits. Note that the assembler will trun- 
cate the value if you specify a field that is not wide enough to contain the 
value. For example, .field 3,1 will cause the assembler to truncate the val- 
ue 3 to1; the assemble also prints the message: 


*xx*xwarning -— value truncated. 


Successive field directives pack values into the specified number of bits in the 
current word. Fields are packed starting at the least significant part of the word, 
moving toward the most significant part as more fields are added. If the assem- 
bler encounters a field size that does not fit into the current word, it writes out 
the word, increments the SPC, and begins packing fields into the next word. 


You can use the .even directive to force the next .field directive to begin pack- 
ing into a new word. If you use a label, it points to the word that contains the 
field. 


Note also that when you use .field in a .struct/.endstruct sequence, .field de- 
fines a member’s size; it does not initialize memory. For more information 
about .struct/.endstruct, refer to Section 4.8. 


Example This example shows how fields are packed into a word. Notice that the SPC 
does not change until a word is filled and the next word is begun. 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


* Initialize a 24-bit field at 

KKK KKK KKK KKK KKK KK KKK KKK KKKKKK KKK KKK KK KK 
00000000 O0bbccdd -field OBBCCDDh, 24 

KKK KKK KKK KKK KKK KKK KK KKK KKK KKKKKK KKK KK KK 

* Initialize a 5-bit field * 

KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KK 
00000000 Oabbccdd .field OAh,5 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


* Initialize a 4-bit field (new) word * 
KKK KKK KK KKK KK KKK KKK KKKKKKKKKKK KKK KKK KKK 


PRPPRPRPRPRPEE 
ODIDUBRWNHKROCODINDA OV BWNHE 


00000001 0000000c -field 0OCh,4 
KKK KKK KK KKK KKK KK KKK KKK KKK KK KKK KKKKKKKKK 
* Initialize a 3-bit field * 
KKK KKK KK KKK KKK KK KKK KK KKK KKK KKKKKKKKK KKK 
00000001 O000001c x: -field 0O1h,3 
KKK KKK KKK KEK KKK KKK KK KKK KKKKKKKAKKKK KKK KK KK 
* Initialize a 32-bit relocatable * 
* field in the next word * 
20 KKK KKK KKK KEK KKK KKK KK KKK KKKKKKKAKKKKKK KK KKK 
21 00000002 00000001’ -field x 
22 


Example 4—7 shows how the directives in this example affect memory. 
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Example 4—7. The .field Directive 


Word Code 
31 30.29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 
field OBBCCDDh, 24 


1011101111001100110111041 


24-bit field 
31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 


01010/101110111100110011011101) field 0Ah,5 


5-bit field 


s 
° 


24-bit field 
31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 


Oo 10| Moni od tao odtoonm aoa) ficld OCh,4 


31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 
1100 


eo 
& 
ae ° 


4-bit field 
31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 
0011100) field O1h,3 


| 
: 


3-bit field 
31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 
0000000000000000000000000|0011100 field x 
31 30 29 28 27 26 25 24 23 22 21 2019181716 1514131211109 8 76543210 
2 100000000000000000000000000000001 


— 
oO 
ww 
a 
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Syntax 


Description 


float value; [, ..., value,] 
-double value; [, ... , value,] 
Jdieee value, [, ... , valuey] 
-Sfloat value; [, ... , value] 


The .float directive places the floating-point representation of one or more 
floating-point constants into successive words in the current section. Each 
value must be either a floating-point constant or a symbol that has been 
equated to a floating-point constant. Each constant is converted to a floating- 
point value in TMS320 single-precision (32-bit) format. 


The .double directive behaves just like the float; it is generated by the 
compiler for double variables. 


The .ieee directive (available with the -v40 assembler option) also behaves 
like the float except that the value is converted to IEEE single-precision 
(32-bit) format. 


The IEEE floating-point format consists of three fields: 


_) A 1-bit sign field (s) 


.) An 8-bit biased exponent (exponent) 
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L) A 23-bit normalized mantissa (mantissa) 


31 30 23 22 16 
15 0 


mantissa 


value = (— 1)* x (1.0 + O.mantissa) x 2ePenent-127 


The .sfloat directive is available only with the -v32 assembler option. The 
.Sfloat directive places the floating-point representation of one or more 
floating-point constants into successive words in the current section. Each 
value must be either a floating-point constant or a symbol that has been 
equated to a floating-point constant. The format is the normal single-precision 
format right-shifted by 16 bits so that: 

_j Bits 31 through 16 are zero 

_j Bits 15 through 8 are the 8-bit exponent 

_] Bit 7 is the sign bit 

_j Bits 6 through 0 are the 7-bit mantissa 


15 8 7 6 0 


The .sfloat directive can be used to place floating point values into 16-bit 
external memory. When the values are loaded into the CPU registers (LDF), 


Example 


the number will be loaded in the upper 16-bits with the lower 16-bits set to 0. 
See page 4-2 of the 1995 TMS320C32 Addendum to the TMS320C 3x User’s 
Guide for more information. 


Note that when you use .float in a .struct/.endstruct sequence, .float defines 
a member’s size; it does not initialize memory. For more information about 
.struct/.endstruct, refer to Section 4.8. 


Here are some examples of the .float directive. 


1 00000000 53fbabat -float -1.0e25 

2 00000001 01400000 -float 3 

3 00000002 06760000 -float 123, 0.5 
00000003 ££000000 

4 0003243f PI: Set 3.14159 

5 O002b7el E: set 2.71828 

6 00000004 01490fd0 -float PI,E 


00000005 012df84d 
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Syntax 


Description 


Example 


global symbol; [,..., symbol] 
def symbol; [,..., symbol] 
-ref symbol; [,..., symbol] 


The .global, .def, and .ref directives identify global symbols, which are defined 
externally, or can be referenced externally. 


Lj The .def directive identifies a symbol that is defined in the current module 
and can be accessed by other files. The assembler places this symbol in 
the the symbol table. 


(1 The.ref directive identifies a symbol that is used in the current module but 
defined in another module. The linker resolves this symbol’s definition at 
link time. 


Lj) The .global directive acts as a .ref or a .def, as needed. 


A global symbol is defined in the same manner as any other symbol; that is, 
it appears as a label or is defined by the .set, .bss, or .usect directive. As with 
all symbols, if a global symbol is defined more than once, the linker issues a 
multiple-definition error. Note that .ref always creates an entry for a symbol, 
whether the module uses the symbol or not; .global, however, creates a sym- 
bol table entry only if the module actually uses the symbol. 


A symbol may be declared global for two reasons: 


1) Ifthe symbol is not defined in the current module (including macro, .copy, 
and include files), the .global or .ref directive tells the assembler that the 
symbol is defined in an external module. This prevents the assembler from 
issuing an unresolved reference error. At link time, the linker looks for the 
symbol’s definition in other modules. 


2) Ifthe symbol is defined in the current module, the .global or .def directive 
declares that the symbol and its definition can be used externally in other 
modules. These types of references are resolved at link time. 


This example uses four files: 


1 file1./st and file3./st are equivalent. Both files define the symbol /nit and 
make it available to other modules; both files use the external symbols x, 
y, and z. file1.lst uses the .global directive to identify these global symbols; 
file3.lst uses .ref and .def to identify the symbols. 


 file2.!st and file4.lst are equivalent. Both files define the symbols x, y, and 
Zand make them available to other modules; both files use the external 
symbol Init. file2.Ist uses the .global directive to identify these global sym- 
bols; file4.lst uses .ref and .def to identify the symbols. 


file1.Ist: 


-global Init ; Global symbol defined in this file 
-global x, Y, Z ; Global symbols defined file2.1st 
Init: ; Symbol definition 
LDI RO,R1 
.word x 
, 
, 
.end 
file2.Ist: 
-global x, Y, Z ; Global symbols defined this file 
-global Init ; Global symbol defined in filel.lst 
xX: .set 1 ; Symbol definitions 
Vi «set 2 
z: .set x + y 
-word Init 
, 
, 
.end 
file3.Ist: 
.def Init ; Global symbol defined in this file 
-ref x, y, Z ; Global symbols defined in file4.lst 
Init: ; Symbol definition 
LDI RO,R1 
-word xX 
, 
, 
, 
.end 
file4.Ist: 
-def x, y, Zz ; Global symbols defined in this file 
-ref Init ; Global symbol defined in file3.l1st 
x: .set 1 ; Symbol definitions 
y: .set 2 
Zz: .set x + y 


-word Init 


.end 
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Syntax 


-hword value; [, ... , valuéy] 


Description The .hword directive places one or more 16-bit values into consecutive words 
in the current section. Each va/ue may be either: 


L 


L 


An expression that the assembler evaluates and treats as a 16-bit signed 


number, or 


A character string enclosed in double quotes. Each character represents 
a separate value. 


Values are not packed or sign extended; each value occupies the least signifi- 
cant 16 bits of a full 32-bit word. 


The assembler truncates any value that is greater than 16 bits. The .hword di- 
rective can have up to 100 operands, but they must fit on a single line. 


If you use a label, it points to the location of the first word that is initialized. 


Example This example assembles several 16-bit values into words in the current sec- 
tion. The label viisthas the value 6Ah, which is the location of the first initialized 
word. 

1 
2 
3  0000006A OO000000A vilist: .-hword10,-1,”abe”,’ab’ 
0000006B OO0O0OFFFF 
0000006C 00000061 
0000006D 00000062 
0000006E 00000063 
OO00006F 00006261 


Syntax if well-defined expression 
assemble code block when the expression is true 
elseif well-defined expression 
assemble code block when the .if expression is false 
and the .elseif expression is true 
.else 
assemble code block when the expression is false 
endif 
terminate condition block 
Description Four directives provide conditional assembly: 

Lj The .if directive marks the beginning of a conditional block. The 
expression is a required parameter. 

m If the expression evaluates to true (nonzero), then the assembler as- 
sembles the code that follows it (up to an .elseif, an .else, or an .endif). 

lm Ifthe expression evaluates to fa/se (0), then the assembler assembles 
code that follows a .elseif (if present), a else (if present), or a .endif (if 
no .elseif or .else is present). 

1 The .elseif directive identifies a block of code to be assembled when the 
.if expression is false (0) and the .elseif expression is true (nonzero). When 
the .elseif expression is false, the assembler continues to a .else (if pres- 
ent) or an .endif. The .elseif directive is optional in the conditional block; 
if an expression is false and there is no .elseif statement, the assembler 
continues with the code that follows a .else (if present) or a .endif. 

(1 The.else directive identifies a block of code that the assembler assembles 
when the .if expression is false (0). This directive is optional in the condi- 
tional block; if an expression is false and there is no .else statement, then 
the assembler continues with the code that follows the .endif. 

_) The .endif directive terminates a conditional block. 


The .elseif and .else directives can be used in the same conditional assembly 
block and can be used more than once within a conditional assembly block. 


For information on the conditional operators that the assembler supports, refer 
to subsection 3.10.6, Conditional Expressions, on page 3-23. 
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Example 
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OANAUPBPWNE 


Here are some examples of conditional assembly: 


00000001 
00000002 
00000003 
00000004 


00000000 00000004 


00000001 0000000a 


syml 
sym2 
sym3 
sym4 


If_4: 


If_5: 


If_6: 


Lf 7% 


Set 
-set 
-set 
~set 
eit 
-byte 
.else 
-byte 
-endif 
sift 
-byte 
.else 
-byte 
-endif 
acl 
-byte 
i) 
-byte 
-endif 
oat 
-byte 
-ifelse 
-endif 


= sym2 * sym2 


* sym2 


<= 10 


7 equal values 


7 unequal values 


; less than/equal 
7 greater than 


'= sym4 + sym2 
7 unequal values 
.else 
7 equal values 


Syntax 


Description 


Example 3 


5 00000070 
6 00000071 
00000072 
00000073 
00000074 
00000075 
00000076 
00000077 


Example 4 


1 00000000 
00000001 


Example 5 


1 00000000 
00000001 
00000002 
00000003 
00000004 


int value; [,..., Valueéy] 
long value; [,..., value,] 
word value; [, ..., value,] 


The .int , .long, and .word directives are equivalent; they place one or more 
values into consecutive 32-bit fields in the current section. Each value is either: 


_j Anexpression that the assembler evaluates and treats as a 32-bit signed 
value, or 


1) Acharacter string enclosed in double quotes. Each character represents 
a separate value. 


The values can be either absolute or relocatable expressions. If an expression 
is relocatable, the assembler generates a relocation entry that refers to the ap- 
propriate symbol; the linker can then correctly patch (relocate) the reference. 
This allows you to initialize memory with pointers to variables or labels. 


You can use as many values as fit on a single line. If you use a label, it points 
to the first word that is initialized. 


This example uses the .int directive to initialize words. Notice that the symbol 
sympir puts the symbol’s address in the object code and generates a relocat- 
able reference (indicated by the ’ character appended to the object word). 


08010000 symptr LDI RO,R1 

OOO0Q0000A -int 10, symptr,-1,”abc”,’ abc’ 
00000070’ 

FEEPFEFEFFF 

00000061 

00000062 

00000063 

00636261 


This example initializes two 32-bit fields and defines DAT1 to point to the first 
location. The contents of the resulting 32-bit fields are FFFFABCDh and 141th. 


FFFFABCD DAT1: .long OFFFFABCDH, ‘A’ +100h 
00000141 


This example initializes five words. The symbol WordX points to the first word. 


00000C80 WordX: .word 3200,1+’AB’ ,—’AF’ ,OF410h, ‘A’ 
00004242 
FFFFBOBF 
O000F410 
00000041 
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Syntax 


Description 


-label symbol 


The .label directive defines a special symbol that refers to the loadtime ad- 
dress rather than the runtime address within the current section. Most sections 
created by the assembler have relocatable addresses. The assembler as- 
sembles each section as if they start at zero, and the linker relocates them to 
the address at which they load and run. 


For some applications, itis desirable to have a section load at one address and 
run ata different address. For example, you may wish to load a block of perfor- 
mance-critical code into slower off-chip memory to save space, and then move 
the code to high-speed on-chip memory to run it. 


Such a section is assigned two addresses at link time: a load address and a 
separate run address. All labels defined in the section are relocated to refer 
to the runtime address so that references to the section (such as branches) 
are correct when the code runs. 


The .label directive creates a special “label” that refers to the loadtime ad- 
dress. This is useful primarily so that the code that relocates the section knows 
where the section was loaded. For example: 


¥ 


; .label Example 


¥ 

-sect “.examp” 

. label examp_load ; load address of section 
start: ; vun address of section <code> 
finish: ; vun address of section end 

. label examp_end ; load address of section end 


For more information about assigning runtime and loadtime addresses in the 
linker, refer to Section 8.8 on page 8-35. 


Syntax double — value 


Description The .ldouble directive places the floating-point representation of along double 
floating-point constant into two consecutive 32-bit words in the current section. 
The value must be a floating-point constant. Each constant is converted to a 
floating-point value in 40-bit LDF/LDI format with a 24-bit overlap. 


Aa 82 bits of first word, 
39 31 7 0 


I 


N—————————__ 32 bits of second word —————~" 


Example Here are some examples of the .ldouble directive. 


1 00000 c520 .ldouble -1.0e25 
00002 8b2a 
00004 2c28 
00006 0291 

2 00008 4008 .1ldouble 3 
0000a 0000 
0000c 0000 
0000e 0000 

3 00010 405e . Ldouble 123 
00012 c000 
00014 0000 
00016 0000 

4 


To load an .Idouble value, execute a LDF and then an LDI into the same data 
register from successive memory locations: 


LDF @var,RO Load upper bits 
LDI @var+1,RO ;Load lower bits 


~ 


The LDF must be performed first, as it clears the lower 8 bits of the register. 
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Syntax 


-length page length 
-width page width 


Description The .length directive sets the page length of the output listing file. It affects the 
current page and following pages; you can reset the page length with another 
length directive. 

_j Default length: 60 lines 

LJ Minimum length: 20 lines 

_j Maximum length: 32,767 lines 

The .width directive sets the page width of the output listing file. It affects the 
next line assembled and following lines; you can reset the page width with an- 
other .width directive. 

(41 Default width: 80 characters 

[1 Minimum width: 80 characters 

(4 Maximum width: 200 characters 

Note that the width refers to a full line in a listing file; the line counter value, SPC 
value, and object code are counted as part of the width of a line. Comments 
and other portions of a source statement that extend beyond the page width 
are truncated in the listing. 

The assembler does not list the .width and .length directives. 

Example The following example sets the page length and page width to various values. 

TMS320C3x/4x COFF Assembler Version X.xx Wed Feb 1 09:55:52 1997 

Copyright 1987-1997 Texas Instruments Incorporated 

***** Length and Width ***** PAGE 1 

2 KKK K KK KKK KKK KK KKK KKK KK KKK KKK KKK KKKKKKKK KKK KKK KK KK 
3 ** The page length is limited to 60 a 
4 xx lines per page. The page width is age 
is) ** limited to 80 characters per line. *% 
6 KKK K KKK KK KKK KK KKK KKK KK KKK KKK KKK KKKKKKKK KKK KKK KK KK 
7 -length 60 
8 .width 80 
9 KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKKKKKKKKKKKKKK 
10 ** The page length is limited to 50 bias 
11 **x lines per page. The page width is heal 
12 ** limited to 200 characters per line. x 
13 KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKKEKK 
14 -length 50 
15 .width 200 
16 
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Syntax 


Description 


Description 


Example 


list 
-Nolist 


The .nolist directive suppresses the source listing output until a .list directive 
is encountered. The .list directive tells the assembler to resume printing the 
source listing after it has been stopped by a .nolist directive. By default, the 
assembler acts as if a .list directive had been specified. The .nolist directive 
can be used to reduce assembly time and the size of the source listing; it can 
be used in macro definitions to inhibit the listing of the macro expansion. 


The .nolist directive suppresses the source listing output until a .list directive 
is encountered. The .list directive tells the assembler to resume printing the 
source listing after it has been stopped by a .nolist directive. By default, the 
assembler behaves as if a .list directive has been specified. The .nolist direc- 
tive can be used to reduce assembly time and the size of the source listing; 
itis frequently used in macro definitions to inhibit the listing of the macro expan- 
sion. 


The assembler does not print the .list or .nolist directives or the source state- 
ments that appear after a .nolist directive; however, it continues to increment 
the line counter. You can nest the .list/.nolist directives; each .nolist needs a 
matching .list to restore the listing. Atthe beginning of an assembly, the assem- 
bler acts as if it has assembled a .list directive. 


Note: Using the .list Directive Without Requesting a Listing File 


If you don’t request a listing file when you invoke the assembler, the assem- 


bler ignores the .list directive. 
| 


This example uses the .copy directive to insert source statements from an- 
other file. The first time this directive is encountered, the assembler lists the 
copied source lines in the listing file. The second time .copy is encountered the 
assembler does not list the copied source lines, because a .nolist directive was 
assembled. Note that the .nolist, the second .copy, and .list directives do not 
appear in the listing file; note also that the line counter is incremented even 
when source statements are not listed. 


Source file: 
.COpy byte.asm 
-nolist 
.COpy byte.asm 
.list 


* Back in original file 
-string "”Done” 
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Listing file: 


1 
A ol 
A 2 
5 
6 


.COpy byte.asm 
** IN BYTE.ASM (copy file) 
00000000 00000020 -byte 32, 1+ ‘A’ 
00000001 00000042 
* Back in original file 
00000004 656e6f44 .string “Done” 


Syntax 


Description 


Example 


-loop [well-defined expression] 
repeatedly assemble code block 
-break [well-defined expression] 


assemble repeatedly while the .break expression is false 
(zero); go to code following .endloop if true (nonzero) 


.endloop 
execute when .break directive is true (nonzero) or when 


number of loops performed equals loop count given 
by .loop 


Three directives enable you to repeatedly assemble a block of code: 


L) The.loop directive begins arepeatable block of code. The optional expres- 
sion evaluates to the loop count (the number of loops to be performed). 
If there isno expression, the loop count defaults to 1024, unless the assem- 
bler first encounters a .break directive with an expression that is true 
(nonzero) or omitted. 


.) The .break directive is optional, along with its expression. When the 
expression is false (0), the loop continues. When the expression is true 
(nonzero), or omitted, the assembler breaks the loop and assembles the 
code after the .endloop directive. 


(1 The .endloop directive terminates a repeatable block of code. 


This example illustrates how these directives can be used with the .eval direc- 
tive. The following assembly language code generates the listing shown on the 
next page. 


Source file: 
.eval O, x 
coef . Loop ;coefficient table 
.word ee 
.eval x. a ly & 
-break x = 6 
.endloop 
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Listing file: 


1 -eval O, x 
2 coef -loop ;coefficient table 
3 
4 .word x * 2 
5 -eval x +1, x 
6 -break x = 6 
7 -endloop 
Al 00000000 00000000 .word OI -** 32 
1 -eval (Ce eed eae 4 
1 -break 1 = 6 
1 00000001 00000002 .word 1 * 2 
1 -eval 1 +1, x 
1 -break 2 = 6 
1 00000002 00000004 .word 2* 2 
1 -eval 2+ 1, & 
1 -break 3 = 6 
1 00000003 00000006 .word 3S 2 
1 -eval St ly -s 
1 -break 4 = 6 
al 00000004 00000008 .word 4 * 2 
alt -eval 4+ 1, x 
alt -break 5 = 6 
1 00000005 0000000a .word 5 * 2 
1 -eval (ome ae eae 4 
1 -break 6 = 6 
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Syntax 


Description 


-mlib = [” ]filename[”’] 


The .mlib directive provides the assembler with the name of a macro library. 
Amacrolibrary is a collection of files that contain macro definitions. These files 
are bound into a single file (called an archive or library) by the archiver. Each 
file ina macro library may contain one macro definition that corresponds to the 
name of the file. Note that: 


_j Macro library members must be source files (not object files). 


_} The filename of a macro library member must be the same as the macro 
name, and its extension must be .asm. 


The filename must follow host operating system conventions; it may be en- 
closed in double quotes. You can specify a full pathname (for example, .mlib 
C:\dsp\macs.lib). If you do not specify a full pathname, the assembler 
searches for the file in: 


1) The directory that contains the current source file. 
2) Any directories named with the -i assembler option. 
3) Any directories specified by the environment variable A_DIR. 


For more information about the -i option and the environment variable, see 
Section 3.5, Naming Alternate Directories for Assembler Input, on page 3-7. 


When the assembler encounters an .mlib directive, it opens the library and cre- 
ates a table of its contents. The assembler enters the names of the individual 
library members into the opcode table as library entries; this redefines any ex- 
isting opcodes or macros that have the same name. If one of these macros is 
called, the assembler extracts the entry from the library and loads it into the 
macro table. The assembler expands the library entry in the same manner as 
other macros, but it does not place the source code into the listing. Only mac- 
ros that are actually called from the library are extracted. 
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Example This example creates a macro library that defines two macros, inc1 and dec?. 
The file inc1.asm contains the definition of inc1, and dec1.asm contains the 
definition of dect. 


incl.asm dec1.asm 
** Macro for incrementing a register ** ** Macro for decrementing a register ** 
nel -macro reg decl -macro reg 

ADDI 1, reg SUBI 1, reg 

.endm .endm 


Use the archiver to create a macro library: 
ar30 -a mac incl.asm decl.asm 


Now you can use the .mlib directive to reference the macro library and call the 
inc1 and deci macros: 


-mlist 

-mlib ”“mac.1ib” 

incl RO ;macro call 
decl R1 ;macro call 


This is the resulting assembly: 


1 -mlist 

2 -mlib "nad. Lab” 

3 00000000 incl RO ;macro call 
1 00000000 02600001 ADDI 1, RO 

4 00000001 decl R1 ;macro call 
1 00000001 18610001 SUBI 1, RI 
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Syntax 


Description 


Example 


OP WNHE 


oor aA 


00000000 
00000000 
00000001 
00000002 


00000003 


0000000a 
0000000a 
0000000b 
0000000c 
0000000d 
0000000e 
OOO00000F 


.mlist 
.mnolist 


Two directives provide you with the ability to control the listing of macro expan- 
sions in the listing file: 


_j) The .mlist directive allows macro expansions in the listing file (default.) 


_} The .mnolist directive inhibits macro expansions in the listing file. 


By default, all macro expansions are listed. The line counter restarts counting 
at 1 during a macro expansion; it resumes counting from its previous value 
when the macro expansion is complete. 


This example defines a macro named str_3. The first time the macro is called, 
the macro expansion is listed (by default). The second time the macro is called, 
the macro expansion is not listed because a .mnolist directive was assembled. 
The third time the macro is called, the macro expansion is again listed because 
a .mlist directive was assembled. 


str_3 «macro parml, parm2, parm3 
-string “:parml:”, "“:parm2:”", “:parm3:” 
.endm 
str_3 "reda”, “green”, “blue” 
67646572 -string “red”, "green”, “blue” 
6e656572 
65756c62 
-mnolist 
str_3 “Raphael”, “Michelangelo”, “Donatello” 
-mlist 
str_3 “Huron”, “Michigan”, “Superior” 
6£727548 -string “Huron”, "Michigan”, "Superior” 
63694d6e 
61676968 
7075536e 
6£697265 
00000072 
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Syntax 


Description 


Example 


«newblock 


The .newblock directive undefines any local labels currently defined. A local 
label, by nature, is temporary; the .newblock directive resets local labels and 
terminates their scope. 


A local label is a label in the form $n, where nis a single decimal digit. A local 
label, like other labels, points to an instruction byte. Unlike other labels, local 
labels cannot be used in expressions; they can be used only as the operand 
in 8-bit jump instructions. Local labels are not included in the symbol table. 


After a local label has been defined and (perhaps) used, you should use the 
-newblock directive to reset it. Note that the .text, .data, and .sect directives 
also reset local labels and that local labels that are defined within an include 
file are not valid outside of the include file. 


This example shows how the local label $1 is declared, reset, and then de- 
clared again. 


1 00000 0223 Labell: mov TA, -E3 
2 00002 ‘'c401 bne $1 
3 00004 1a03 mov #-1, 4x3 
00006 ffft 
4 00008 6031 $1 cmp £37. FL 
5 .- newblock ; undefine $1 
6 0000a ‘'’c400 bne $1 
7 0000c 8213 inc r3 
8 0000e 3034 $1 add r3, r4 
9 


Syntax 


Description 


option option list 


The .option directive selects several options for the assembler output listing. 
The option list is a list of options separated by commas; each option selects 
a listing feature. Valid options include: 

B Limits the listing of .oyte directives to one line. 

Resets the B, M, T, and W options. 

Limit the listing of .hword directives to one line. 

Limit the listing of .long, .int, and .word directives to one line. 

Turns off macro expansions in the listing. 


Limits the listing of .string directives to one line. 


<x<aodo2ristit 


Produces a symbol cross-reference listing. 


Options are not case sensitive. 


4-57 


Example This example limits the listings of the .byte, .hword, .long, .word, .int, and 
.string directives to one line each. 


‘ll KKK KK KKK KKK KKK KK KKK KK KKK KKK KKKKK KK KKK KKK 
2 * Limit the listing of .byte, .word, * 
3 *  .string directives to 1 line each = 
4 KKK KKK KK KKK KKK KKK KKKKKKKKKKKK KKK KK KKK KKK 
5 -option B, W, T 

6 0000 bd . byte -'C’, OBOh, 5 

7 0003 l5aa .word 5546, 78h 

8 0007 59 -string “YES” 

9 KKK KK KKK KK KKK KK KKK KKK KKKKKKKKKK KK KKK KKK 
10 * Reset the listing options st 
11 KKK KKK KK KKK KKK KKK KKKKKKKKKKKK KKK KK KKK KKK 
12 -option F 
13 000a bd -byte -'C’, OBOh, 5 

000b bO 

000c 05 
14 000d 1l5aa -word 5546, 78h 

OOOf 0078 
15 0011 59 -string “YES” 

0012 45 

0013 53 
16 KKK KKK KK KKK KKK KKKKKKKKKKKKKKK KKK KKK KK KKK 
17 * Use the A option to ignore all * 
18 * other options and directives * 
19 KKK KKK KK KKK KKK KKK KKKKKKKKKKKK KKK KKK KK KKK 
20 -option A 
21 -nolist 
22 -option B, W, T 
23 0014 bd .byte -'C’, OBOh, 5 

0015 bo 

0016 05 
24 0017 1l5aa -word 5546, 78h 

0019 0078 
25 001b 59 -Sstring "YES” 

001c 45 

001d 53 
26 -list 
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Syntax -page 


Description The .page directive produces a page eject in the listing file. The source state- 
ment is not printed in the source listing, but the line counter is incremented. 
Using the .page directive to divide the source listing into logical divisions im- 
proves program readability. 


Example This example causes the assembler to begin a new page of the source listing. 


This is the source file: 


.title ”**** The PAGE DIRECTIVE ****” 
-string "Page 1” 


.page ;the directive won’t be printed 
.string "Page 2” 


This is the listing file: 


TMS320C3x/4x COFF Assembler Version xX.xx Wed Feb 1 11:09:27 1997 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
*x*x*x The PAGE DIRECTIVE **** PAGE 1 
2 00000000 65676150 .string “Page 1” 
00000001 00003120 
TMS320C3x/4x COFF Assembler Version xX.xx Wed Feb 1 11:09:27 1997 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
*xx*x* The PAGE DIRECTIVE **** PAGE 2 
4 00000002 65676150 .string "Page 2” 


00000003 00003220 
5 
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Syntax 


Description 


Example 


-regalias 


The .regalias directive allows registers named Fn to be aliases for 
floating-point versions of Rn data registers. This type of aliasing makes 
floating-point operations more obvious within the assembly code. 


This directive should be placed near the beginning of an assembly file. The 
assembler does not accept F register aliasing by default, since you may have 
existing code that uses F aliases for other purposes. 


The code generator uses this directive in every file it creates, because it always 
refers to F registers in floating-point instructions. 


The code below displays assembly instructions without F aliasing: 


addi EL r2,. £3 
sti r3,@C1 
addf r4,r5,r6 
stf r6, @C2 
fix r3,x3 


Here is the equivalent code that includes the .regalias directive and F aliasing: 


.regalias 

addi r1,22,x3 
sti r3,@C1 
addf £4, £5,£6 
stft £6, @C2 
fix £3,763 


Syntax 


Description 


Example 


PRPRPPRPRPRPRPEE 
CMDINIDUBRWNPOODRIDUHAWNE 


No 
oO 


NNN ND 
PWN Ee 


00000000 
00000000 
00000001 


00000000 
00000000 
00000001 
00000002 


00000002 
00000002 
00000003 
00000004 


00000003 
00000003 


sect ”section name” [, value] 


The .sect directive defines named sections that are used like the default .text 
and .data sections. The .sect directive begins assembling source code into the 
named section. Named sections can be used for data or code that must be allo- 
cated into memory separately from .text or .data. 


The section name identifies a section that the assembler assembles code into. 
The name is significant to 8 characters and may be enclosed in quotes. 


Note that the .asect directive is similar to the .sect directive; however, .asect 
creates a named section that has absolute addresses. If you use the .asect 
directive to define an absolute named section, you can use the .sect directive 
later in the program to continue assembling code into the absolute section. 


Chapter 2 provides additional information about named sections. 


This example defines a section, Sym_Defs, and assembles code into it. 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


** Begin assembling into .text te 
KKEKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK 
«text 
07020001 LDF R1,R2 
07040003 LDF R3,R4 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK 
** Begin assembling into Sym_.Defs paul 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK 
-sect "Sym_Defs” 
0148£5c3 -float 3.14 
0000000Ff -hword OFh 
07060005 LDF R5,R6 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK 
** Resume assembling into .text ae 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK 
-text 
080a0009 LDI AR1, AR2 
00000003 -byte 3,4 
00000004 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KK 
** Resume assembling into Sym_.Defs ile 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KK 
-sect "Sym_Defs” 
aabbccdd . Long Oaabbccddh 
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Syntax 


Description 


Example 


4-62 


AYNADAUOBWNEH 


ie) 


10 
11 
12 
13 
14 
15 


symbol .set value 
symbol .equ_ value 


The .set and .equ directives equate a constant value to a symbol. The symbol 
can then be used in place of a value in assembly source. This allows you to 
equate meaningful names with constants and other values. The .set and .equ 
directives are identical and can be used interchangeably. 


_} The symbol must appear in the label field. 


(j} The value must be a well-defined expression; that is, all symbols in the 
expression must have been previously defined in the current module. 


Undefined symbols or symbols that are defined later in the module cannot be 
used in the expression. If the expression is relocatable, the symbol to which 
it is assigned is also relocatable. 


The value of the expression appears in the object field of the listing. This value 
is not part of the actual object code and is not written to the output file. 


Symbols defined with .set can be made externally visible with the .def or .global 
directive. In this way you can define “global” absolute constants. 


The .asg directive can be used in many of the same ways as the .set directive, 
but while .set assigns a constant value (cannot be redefined) to a symbol, .asg 
assigns a string (can be redefined) to a substitution symbol. 

This example shows how symbols can be assigned with .set. 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK 


** Equate symbol FP with register AR3 Bo 
KAEKKKKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK 


0000000b FP set AR3 


00000000 0840c300 LDI *FP, RO 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KK KKK KKK 


** Set symbol “count” to an integer and ** 
** use it as an immediate operand me 
KKK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK 


0000012c count .set 300 


00000001 0860012c LDI count, RO 


KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK 


** Set PI and use it as a constant ae 
KKK KKK KKK KK KKK KKK KKK KK KKK KKKKKKKKK KK KKKK KKK 


0003243£f PI -equ 3.141592654 


16 00000002 01490fdb -float PI 


Syntax 


Description 


Example 


00000000 
00000000 
00000001 
00000002 


OweWNE 


10 00000003 
11 00000067 
12 00000068 


-Space size in words 


The .space directive reserves size number of words in the current section and 
fills them with Os. The section program counter is incremented to point to the 
word following the reserved space. 


The .space directive is equivalent to size number of .word 0 directives. 


This example reserves 100 0-filled words in the .text section. Note that the 
SPC equals 03h before the .space directive is assembled; after the .space di- 
rective is assembled, the SPC is incremented to equal 067h. 


KKK KK KKK KK KKK KKK KKK KKK KKK KKK KK KK KK KK KKK KK 


* Begin assembling into .text ss 
KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKK KKK KKK 
-text 
0000000a .word OAh, OBh 
0000000b 
00305241 -string “ARO” 
KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK 
* Reserve a block of 100 words in .text * 
KKKKKKKKKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKKKK 
00000000 Sp_xX: -space 100 
0000000c .word OCh , Still in .text 
00000003’ -word Sp_X 


Figure 4-2. The .space Directive 


Oh} 0000000A 
0000000B 
00305241 


3h 


100 words 
reserved 


67h} oooo000c 
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Syntax 


Description 


Example 
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.sslist 
.ssnolist 


Two directives enable you to control substitution symbol expansion in the list- 
ing file: 


_} The.sslist directive allows substitution symbol expansion in the listing file. 
The expanded line appears below the actual source line. 


(1 The.ssnolist directive inhibits substitution symbol expansion in the listing 
file. 


By default, all substitution symbol expansion in the listing file is inhibited. The 
lines with the pound (#) character denote expanded substitution symbols. 


This example shows code that by default (.ssnolist directive) inhibits the listing 
of substitution symbol expansion, and it shows the .sslist directive assembled, 
which tells the assembler to list substitution symbol code expansion. 


1 00000000 .bss x, 1 
2 00000001 .bss y, 1 
3 ADDTWO .macro a, b, reg 
4 LDI @a, reg 
5 ADDI @b, reg 
6 STI reg, @98EAh 
7 .endm 
8 
9 00000000 ADDTWO x,y,RO 
1 00000000 08200000- LDI @x, RO 
1 00000001 02200001- ADDI @y, RO 
1 00000002 152098ea STI RO, @98EAh 
10 -sslist 
11 00000003 ADDTWO x,y,R1 
1 00000003 08210000- LDI @a, reg 
# LDI @x, R1 
1 00000004 02210001- ADDI @b, reg 
te ADDI @y, Rl 
1 00000005 152198ea STI reg, @98EAh 
# STI R1, @98EAh 


Syntax 


Description 


Example 


string "string;” [, ... , ”stringy”| 


The .string directive places 8-bit characters from acharacter string into the cur- 
rent section. The data is packed so that each word contains four 8-bit values. 
Each string is either: 


_j Anexpression that the assembler will evaluate and treat as a 32-bit signed 
number, or 


1) Acharacter string enclosed in double quotes. Each character represents 
a separate value. 


Values are packed into words, starting with the least significant byte of the 
word and moving toward the most significant portion as more bytes are added. 
Any unused space is padded with null bytes (Os). This directive differs from 
.byte in that .byte does not pack values into words. 


The assembler truncates any values that are greater than 8 bits. You may have 
up to 100 operands, but they must fit on a single source statement line. 


If you use a label, it points to the first word that is initialized. 


This example places 8-bit values into words in the current section. 


1 00000000 44434241 Str_3: . string ”“BBCD” 

2 00000001 54535251 . string 51h, 52h, 53h, 54h 

3 00000002 73756F48 . String “Houston” 
00000003 OO06E6F74 

4 00000004 00000030 . string 36 + 12 
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Syntax 


Description 


[ stag | 
[ memo | 
[ mem, ] 


[ memn, ] 


[ memy ] 
[ size ] 


label 


Struct [ expr | 
element [ expr | 
element [ expry | 
.tag stag [ expry] 
element [ exon | 
-endstruct 

.tag stag 


The .struct directive assigns symbolic offsets to the elements of a data struc- 
ture definition. This enables you to group similar data elements together and 
then let the assembler do the element offset calculation. This is similar to a C 
structure or a Pascal record. The .struct directive does not allocate any 
memory; it merely creates a symbolic template that can be used repeatedly. 


The .tag directive gives structure characteristics to a label, simplifying the sym- 
bolic representation and providing the ability to define structures that contain 
other structures. .tag does not allocate memory. The structure tag (stag) of a 
.tag directive must have been previously defined. 


[ stag | 


[ expr] 


[ memp | 


element 


[ expm | 


[ size | 


Is the structure’s tag. Its value is associated with the beginning of 
the structure. If no stag is present, this tells the assembler to put the 
structure members in the global symbol table with their value being 
their absolute offset from the top of the structure. 


Is an expression indicating the beginning offset of the structure. 
Structures default to start at 0. 


Is a label for a member of the structure. This label is absolute and 
equates to the present offset from the beginning of the structure. 
A label for a member structure cannot be declared global. 


Is one of the following descriptors: .string, .byte, .word, .float, .tag, 
.struct, and .field. All of these, except .tag, are typical directives that 
initialize memory. Following a .struct directive, these directives de- 
scribe the structure element's size. They do not allocate memory. 
A .tag directive is a special case because a stag must be specified 
(as in the definition). 


Is an expression for the number of elements described. This value 
defaults to 1. Note that a .string element is considered to be one 
byte in size, and a .field element is one bit. 


Is a label for the total size of the structure. 


Example 1 


Example 2 


Example 3 


Example 4 


al 

2 

3 

4 

5 

6 0000 
7 

8 0000 
6 
7 
8 


12 0000 


14 0000 
15 0003 


11 0000 


13 0000 
14 0003 


—_——_————[jjan__——_aao=>_S_—_—Vaooe=>___vqwavaw_ 1 55 5 50 56S eee 
Note: The Types of Directives That Can Appear in a struct/.endstruct 
Sequence 


The only directives that can appear in a .struct/.endstruct sequence are 
element descriptors, conditional assembly directives, and the .align 
directive, which aligns the member offsets on byte boundaries. Note that 


empty structures are illegal. 
eee) 


0000 real_rec .struct 7 stag 
0000 nom -byte ; memberl = 0 
0001 den -byte 7 member2 = 1 
0002 real_len .endstruct ; real_len = 2 
-8a0001 mov &real+real_rec.den, Aj; access 
-bss real, real_len ; allocate 
0000 cplx_rec .struct 7 stag 
0000 reali -tag real_rec ; memberl = 0 
0002 imagi -tag real_rec ; member2 = 2 
0004 cplx_len .endstruct ; cplx_len = 4 


complex .tag cplx_rec 
-bss complex, cplx_len ; allocate 


-—8a0002 mov &complex.imagi.nom, A 
-—8d0001 cmp &complex.reali.den, A 
0000 -struct 7; no stag puts memNs into 
0000 7 global symbol table 
0000 x -byte ; create 3 dim templates 
0001 y -byte 
0002 vA -byte 
-endstruct 
0000 bit_rec.struct ; stag 
0000 stream .string 64 
0040 bit -field 7 
0040 bitl -field 1 
0041 bit5 -field 5 
0042 x_int .byte 
0043 bit_len.endstruct 
bits .tag bit_rec 


-bss bits, bit_len 


-—8a0040 mov &bits.bit7, A ; load field 
237£ and #7fh, A 7 mask off garbage 
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Syntax 


Description 


Example 
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AANDUBRWNE 


00000000 
00000001 
00000002 


00000003 
00000004 
00000005 


00000006 
00000007 
00000008 


tab size 


The .tab directive defines the tab size. Tabs encountered in the source input 
will be translated to size spaces in the listing. The default tab size is eight. 


Each of the following lines consists of a single tab character followed by a NOP 
instruction, another tab, and a comment. 


0c800000 
0c800000 
0c800000 


0c800000 
0c800000 
0c800000 


0c800000 
0c800000 
0c800000 


, Gefault tab size 


nop 
nop 
nop 

-tab 4 

nop ;no-op 

nop ;no-op 

nop ;no-op 


;no-op 
;no-op 
;no-op 
.tab 16 
nop ;no-op 
nop ;no-op 
nop ;no-op 


Syntax 


Description 


Example 


00000000 
00000001 
00000002 


00000000 
00000000 
00000001 


00000003 
00000003 


.text 


The .text directive tells the assembler to begin assembling into the .text sec- 
tion, which typically contains executable code. The section program counter 
is set to 0 if nothing has yet been assembled into the .text section. If code has 
already been assembled into the .text section, the section program counter re- 
sumes its previous value in the section. 


Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the .text 
section unless you specify one of the other initialized-section directives (.data, 
.sect, or .asect). 


For more information about COFF sections, see Chapter 2. 


This example assembles code into the .text and .data sections. The .text sec- 
tion contains bytes 1, 2, 3, and 4, and the .data section contains bytes 5, 6, 7, 
and 8. 


KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK 


** ,text section (default) iste 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK 
00000001 -byte 1 
00000002 -byte 2,3 
00000003 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK KKK KK 
** switch to .data + 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 
-data 
00000007 -byte 7,8 
00000008 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 
** Resume assembling into .text pal 
KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK 
-text 
00000004 -byte 4 
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Syntax 


title =” string” 


Description The .title directive supplies a title that is printed in the heading on each listing 

page. The source statement itself is not printed, but the line counter is incre- 
mented. The string is a quote-enclosed title of up to 50 characters. If you sup- 
ply more than 50 characters, the assembler truncates the string and issues a 
warning. 
The assembler prints the title on the page that follows the directive, and on sub- 
sequent pages until another .title directive is processed. If you want a title on 
the first page of a listing, then the first source statement must be a .title direc- 
tive. 

Example This example prints the title **** Floating Point Routines **** in the page head- 
ings of the source listing. 

Source file: 
-title "kkkk Floating Point Routines ****” 
Listing file: 

TMS320C3x/4x COFF Assembler Version xX.xx Wed Feb 1 11:09:27 1997 

Copyright 1987-1997 Texas Instruments Incorporated 

xx*x* Floating Point Routines **** PAGE 1 


Syntax 


Description 


Example 


symbol .usect section name”, size in words |, word alignment flag] 


The .usect directive reserves space for variables in an uninitialized, named 
section. This directive is similar to the .bss directive; both simply reserve space 
for data and have no contents. However, .usect defines additional sections 
that can be placed anywhere in memory, independenily of the .bss section. 


[J The symbol! points to the first location reserved by this invocation of the 
.usect directive. The symbo/ corresponds to the name of the variable that 
you're reserving space for. 


(j) Only the first 8 characters of the section name are significant. The section 
name may be enclosed in quotes. This parameter names the uninitialized 
section. 


Lj The sizeis an expression that defines the number of words that will be re- 
served in section name. 


Other sections directives (.text, .data, .sect, and .asect) end the current sec- 
tion and tell the assembler to begin assembling into another section. The 
.usect and the .bss directives, however, do not affect the current section. The 
assembler assembles the .usect and the .bss directives and then resumes as- 
sembling into the current section. 


You can repeat the .usect directive to define more than one variable in the 
specified section. Variables that can be located contiguously in memory can 
be defined in the same section by using multiple .usect directives with the 
same section name. 


For more information about COFF sections, see Chapter 2. 


This example uses the .usect directive to define two uninitialized, named sec- 
tions, var? and var2. The symbol pir points to the first word reserved in the var1 
section. The symbol array points to the first word in a block of 100 words re- 
served in var1, and dflag points to the first word in a block of 50 words in var1. 
The symbol vec points to the first word reserved in the var2 section. 


Figure 4-3 on page 4-72 shows how this example reserves space in two 
uninitialized sections, var1 and var2. 


Example 4-8. Defining Two Uninitialized, Named Sections 


1 KEK KKK KKK KKK KKK KKK KKK KKK KKK KKKKK KKK KK KK 
2 * Assemble into .text ss 
3 KEKE KKK KKK KKK KKK KKK KKKKKKKK KKK KK KKK KK KK 
4 00000000 -text 
5 00000000 08010000 LDI RO,R1 
6 KKK KKK KKK KKK KKK KKK KKK KKKEKKKKKKKK KKK KK KK 
7 * Reserve 1 word in varl bag 
8 KKK K KKK KKK KKK KKK KKKKKEKKKKKKKKKKK KKK KK KK 
9 00000000 ptr -usect "varl”, 1 
10 KKK KKK KKK KK KKK KKK KKK KK KK KKKKKAKKKKKAKKKKEK 
2. * Reserve 100 more words in varl * 
12 KKK KKK KKK KKK KEK KKK KKK KK KKKKKKKAK KKK KKKKAKK 
13 00000001 array -usect “varl”, 100 
14 00000001 08020001 LDI R1,R2 ; Still in .text 
15 KKK KKK KKK KK KKK KKK KEK KKK KKK KKKKKKKKKAKKKKK 
16 * Reserve 50 more words in varl *. 
Ly KKK KKK KKK KK KKK KKK KKK KK KKKKKKKAK KKK KKKKKK 
18 00000065 dflag -usect "“varl”, 50 
19 00000002 08030002 LDI R2,R3 ; Still in .text 
20 KKRK KKK KKK KKK KEK KKK KKK KK KKKKKKKK KKK KKK KAKK 
21 * Reserve 100 words in var2 * 
22 KKK KKK KKK KKK KK KKK KKK KEK KKK KKK KKK KKKKEKKKK 
23 00000000 vec -usect "var2”", 100 
24 00000003 08200000- LDI @vec,RO ; Still in .text 
25 KKK KKK KKK KK KKK KKK KKK KKKKEKKKKKKKKK KKK KKK 
26 * Declare an external .usect symbol a 
Dy. KKK KKK KKK KEK KKK KKK KKK KKK KEK KKK KKK KKKKKKKK 
28 -global array 
29 


Figure 4-3. The .usect Directive 


section var1 section var2 
ptr vec 
array 
100 words 
100 words 
100 words reserved in var2 
dflag 


50 words 


151 words reserved in var1 
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Syntax 


Description 


Example 


version generation number 


The .version directive tells the assembler which generation processor this 
code is for. Valid generation numbers are 30, 31, 32, 40 and 44. The default 
is 30.The version directive must appear before an instruction or directive, or 
else an error will occur. The version directive can be used instead of the —v 
command line option. 


Inthis example, the code will always be assembled and linked for the C40 pro- 
cessor unless overridden by a —v command line option: 


-version 40 
ADDI 5, *+ARO(5), RO 


; target is TMS320C40 
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Chapter 5 


Instruction Set 


The TMS320C3x/C4x assembler supports a base set of general-purpose 
instructions as well as arithmetic instructions that are particularly suited for 
digital signal processing and other numeric-intensive applications. 


This chapter does not cover topics such as opcodes or instruction timing; the 
TMS320C3x User’s Guide and TMS320C4x User’s Guide discuss the 
instruction set in detail. Those user’s guides also contain an alphabetical pre- 
sentation, which is similar to the directives reference in Chapter 4 of this book. 


This chapter provides a general summary of the TMS320C3x and 
TMS320C4x instruction sets: 


LJ Section 5.1 lists information that will help you use the instruction set, 
including addressing modes, optional syntaxes, condition codes and 
flags, and abbreviations and symbols. 


(J Section 5.2 describes the instructions according to function. 


(J Section 5.3 contains the instruction set summary table, which provides 
each instruction’s syntax, operation, and description. 


Topic Page 
5.1 Using the Instruction Set Summary ..........--.:..eeeeeeeee eens 5-2| 
5.2 Functional Summary of the Instruction Set ...................++. 
5.3 Instruction Set Summary Table ............000c cece eee eee eee 
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Using the Instruction Set Summary 


5.1 Using the Instruction Set Summary 


5.1.1 


5-2 


This section summarizes addressing modes, optional syntaxes, condition 
codes and flags, and symbols and abbreviations used in the summary table. 


Addressing Modes 


The TMS320C3x and TMS320C4x User’s Guides discuss addressing modes 
in detail. In some cases, the addressing modes are different for the 
TMS320C30 and TMS320C40: 


(1 General addressing modes 


Register mode: The operand is a CPU register. For floating-point 
operations, use an extended register, (RO—R7) (RO—R11 on the C40). For 
integer operations, use any register. 


Direct mode:. The operand is the contents of a 32-bit address, specified 
by @addr. The 16 MSBs of the address are specified by the DP register; 
the 16 LSBs are specified by the instruction word. On the C30, addresses 
are limited to 24 bits. 


Indirect mode: An auxiliary register contains the address of the operand. 
Table 5-1 lists the various forms that indirect operands may take. The 
displacement may be specified as a value from 0-255 or as one of the 
index registers (IRO or IR1). 


It is not necessary to specify the displacement if it is 1, because the 
assembler assumes a default displacement of 1. For example, *++ARn is 
equivalent to *++ARn(1). 


Short immediate mode: The operand is a 16-bit immediate value. Short 
immediate operands may be signed integers, unsigned integers, or 
floating-point values, depending on the instruction. 


Three-operand addressing modes 

All three-operand instructions are written OP3 src2, src1, dest 
OP opcode, 3 is optional 
src2, src1 operands (see Table 5—1 for legal combinations) 
dest destination register 


Register mode: Same as for general addressing modes. Must be RO-R7 
for floating-point operations. 


Indirect mode with 1-bit displacement: Same as for general addressing 
modes, except the displacement is limited to 0, 1, IRO, or IR1. 
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Immediate mode (C40 Only): The operand is a 5-bit signed integer 
constant in the range —16 to15. This mode is available for integer opera- 
tions only. 


Indirect mode with 5-bit displacement (C40 only): *+AR (0 to 31) 


Parallel addressing modes 


Register mode: The operand is an extended register (RO—R7). In some 
cases, only RO/R1 or R2/R3 can be used as an operand. 


Indirect mode: Same as for general addressing modes, except that the 
displacement is limited to 0, 1, IRO, or IR1. 


Conditional-branch addressing modes 
Register mode: The contents of the register are loaded into the PC. 


PC-relative mode: A signed 16-bit or 24-bit displacement (LSBs of the 
instruction word) is added to the PC. The destination address is usually 
specified as a label; the assembler calculates the displacement. 


Table 5-1. Indirect Addressing 


Operand 
*ARn 
*+ARn(disp) 
*ARn(disp) 
*++ARn(disp 


_— 

xo 

= 
+ 


*ARn++(disp 


Description 


Indirect with no displacement 


Indirect with predisplacement or preindex add 


Indirect with predisplacement or preindex subtract 


Indirect with predisplacement or preindex add and modification 


Indirect with predisplacement or preindex subtract and modification 


Indirect with postdisplacement or postindex add and modification 


Indirect with postdisplacement or postindex subtract and modification 


Indirect with postindex (IRO) and bit-reversed modification 


T Optional circular modification (specified by %) 


5.1.2 Optional Syntax 


The assembler allows a relaxed syntax form for several instructions. These 
optional forms simplify the assembly language so that you can ignore special- 
case syntax for some instructions. 


| 


If the source and destination register are the same, you need specify the 
register only once. Instructions that can use this optional syntax include: 
ABSF, ABSI, FIX, FLOAT, NEGB, NEGF, NEGI, NORM, NOT, RND, 
RCPF, RSQFF, TOIEEE, FRIEEE, SIGI. For example, 
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ABSI RO,RO can be written as ABSI RO 


(1 You can omit the displacement for indirect operands; the assembler will 
assume a displacement of 1. Instructions that use general addressing 
modes, three-operand addressing modes, or parallel addressing modes 
may have indirect address operands. For example, 


LDI *ARO++(1),RO can be written as LDI *~ARO++,RO0 


[1 Immediate-mode operands can be written with an @ symbol. The branch 
and call instructions can use this optional syntax. For example, 


BR label can be written as BR @label 
(1 All 3-operand instructions can be written without the 3. For example, 
ADDI3 RO,R1,R2 can be written as ADDI RO,R1,R2 


_j All conditional instructions accept the suffix U to indicate unconditional 
operation. Also, the U can be omitted from unconditional short branch 
instructions. For example, 


BU label can be written as B label 
(| Labels can be written with or without a trailing colon. For example, 
label0: NOP can be written as labelO NOP 
_] STIK can be written as STI: 
STIK 5, *AR1 can be written as STI 5, *“AR1 


(j) Any commutative 3-operand instruction can be written with the operands 
in any order. This applies to ADDC, ADDI, MPYI, AND, OR, XOR, ADDF, 
MPYF, MPYSHI, MPYUI, TSTB. 


ADDI8 10,*AR3++(1),R2 can be written as ADDI *AR3+(1),10,R2 


5.1.3. Condition Codes and Flags 


The TMS320C3x/C4x assembler provides 20 condition codes (00000-10100 
excluding 01011) and seven condition flags for use with the conditional instruc- 
tions, such as RETScond or LDF cond. 


The conditions include signed and unsigned comparisons, comparisons to 
zero, and comparisons based on the status of individual condition flags. Note 
that all conditional instructions can accept the suffix U to indicate unconditional 
operation. 


The seven condition flags supply information about properties of the result of 
arithmetic and logical instructions. The condition flags are stored in the status 
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register (ST) and are affected by an instruction according to the SET COND 
bit of the status register. 


Table 5—2 summarizes the condition codes and flags: 
Table 5-2. Condition Codes and Flags 


Unconditional Compares 


Condition Code Description Flag 
U 00000 Unconditional Don’t care 
Unsigned Compares 

LO 00001 Lower than Cc 

LS 00010 Lower than or same as CORZ 

HI 00011 Higher than ~C AND ~Z 

HS 00100 Higher than or same as ~C 

EQ 00101 Equal to Z 

NE 00110 Not Equal to ~Z 
Signed Compares 

L 00111 Less than N 

LE 01000 Less than or equal to NORZ 

GT 01001 Greater than ~N AND ~Z 

GE 01010 Greater than or equal to ~N 

EQ 00101 Equal to Z 

NE 00110 Not equal to ~Z 
Compare to Zero 

Z 00101 Zero Z 

NZ 00110 Not zero Z 

p 01001 Positive ~N AND ~Z 

N 00111 Negative N 

NN 01010 Nonnegative ~N 
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Table 5—2 Condition Codes and Flags (Continued) 


Compare to Condition Flags 


NN 01010 Nonnegative ~N 

N 00111 Negative N 

NZ 00110 Nonzero ~Z 

Z 00101 Zero Zz 

NV 01100 No overflow ~V 

Vv 01101 Overflow Vv 
NUF 01110 No underflow ~UF 
UF 01111 Underflow UF 
NC 00100 No carry = 

C 00001 Carry C 
NLV 10000 No latched overflow ~LV 
LV 10001 Latched overflow LV 
NLUF 10010 No latched floating-point underflow ~LUF 
LUF 10011 Latched floating-point underflow LUF 
ZF _ 10100 Zero or floating-point undertow _ 2 OR UF 


Note: The ~ means logical complement . 


5.1.4 Symbols and Abbreviations 


Table 5-3 lists the symbols and abbreviations used in the individual instruction 
descriptions. 


Table 5—3. Instruction Symbols 


Symbol Meaning 

src Source operand 

src Source operand 1 

src2 Source operand 2 

src3 Source operand 3 

src4 Source operand 4 

dst Destination operand 

dst1 Destination operand 1 

dst2 Destination operand 2 

disp Displacement 

cond Condition 

count Shift count 

G General addressing modes 

T Three-operand addressing modes 
P Parallel addressing modes 

B Conditional-branch addressing modes 
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Table 5-3 Instruction Symbols (Continued) 


Symbol 
ARn 


Meaning 


Auxiliary register n 


IRn 
Rn 
RC 
RE 
RS 
ST 


Xx>y 
x(man) 
x(€xp) 


Index register n 

Register address n 

Repeat count register 
Repeat end address register 
Repeat start address register 
Status register 


Carry bit 

Global interrupt enable bit 
Trap vector 

Program counter 

Repeat mode flag 
System stack pointer 


Absolute value of x 

Assign the value of x to destination y 
Mantissa field (sign + fraction) of x 
Exponent field of x 
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5.2 Functional Summary of the Instruction Set 


5.2.1 


The TMS320C3x/C4x instruction set is exceptionally well-suited to digital sig- 
nal processing and other numeric-intensive applications. All instructions are 
a single machine word long, and most instructions take a single cycle to ex- 
ecute. 


The instruction set contains 135 instructions organized into the following 
functional groups: 


Subject 
Load and SiOre wives ae ora eran eae tae eee eae ee awe era 
PATIL GUC ccecta le gece 2 ant ae nai aa Seka tate anaiai at Al eieue ay earatai sence ta aodincaie Se aeaee 
LOGIC cor. ctedeenedhineetedi deeds eeetieaeiebaedwaaddeamdaas 
Program Control sccc2 sacet band ded dea Pedaad Dadee wad Dace 
Interlocked Operations .......... 0000 e cece e eee es 
CONVEISION: canis Quwde horde dada Mik ida das i sade ka ea ceed 
Three Operand ........ 0.00 ects 
Parallel isd ct dincd atakeatdee dead Sedeehe kde ae hale ences bas eee 
TMS320C40 only .... 0.0... ccc ccc nee e nee nee 
LDP and LDPK Instructions 


Load-and-Store Instructions 


The TMS320C3x and TMS320C4x support 23 load and store instructions, 
which are summarized in Table 5—4. These instructions: 


(} Load a word from memory into a register, 


(1 Store a word from a register into memory, or 


1 Manipulate data on the system stack. 


Two of these instructions can load data conditionally. This is useful for locating 
the maximum or minimum value in a data set. See the TMS320C4x User's 
Guide for more information about the condition codes. 


Functional Summary of the Instruction Set 


Table 5-4. Summary of Load-and-Store Instructions 


Instruction 
LBb 
LBUb 
LDA 

LDE 

LDF 
LDFcond 
LDHI 

LDI 
LDIcond 
LDM 
LDPE 


LDPK 
LHW 
LHUw 
LWLct 
LWRet 
POPF 
PUSH 
PUSHF 
STF 
STI 
STIK 


Description 

Load byte (signed) 

Load byte (unsigned) 

Load address register 

Load floating-point exponent 

Load floating-point value 

Load floating-point value conditionally 
Load 16-bit unsigned immediate into 16 MSBs 
Load integer 

Load integer conditionally 

Load floating-point mantissa 


Load integer, 
primary register to expansion file register 


Load DP register immediate 

Load half-word signed 

Load half-word unsigned 

Load word left-shifted 

Load word right-shifted 

Pop floating-point value from stack 
Push integer on stack 

Push floating-point value on stack 
Store floating-point value 

Store integer 

Store integer immediate 


Instruction Set 


*C4x Only 
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5.2.2 Arithmetic Instructions 


The TMS320C3x and TMS320C4x support a complete set of arithmetic in- 
structions. These instructions provide integer operations, floating-point 
operations, and multiprecision arithmetic. Table 5-5 summarizes these in- 


structions. 


Table 5—5. Summary of Arithmetic Instructions 


Instruction 
ABSF 
ABSI 
ADDC t 
ADDF + 
ADDI t 
ASH t 
CMPF + 
CMPI t 
FIX 
FLOAT 
MPYF + 
MPYI t 
MPYSHI t 
MPYUHI fT 
NEGB 
NEGF 
NEGI 
NORM 
RCPR 
RND 
RSQRF 
SUBB t 
SUBC 
SUBF t+ 
SUBRB 
SUBRF 
SUBRI 


Description *C4x Only 
Absolute value of a floating-point number 

Absolute value of an integer 

Add integers with carry 

Add floating-point values 

Add integers 

Arithmetic shift 

Compare floating-point values 

Compare integers 

Convert floating-point value to integer 

Convert integer to floating-point value 

Multiply floating-point values 

Multiply integers 

Multiply signed integers; store 32 MSB product V 
Multiply unsigned integers; store 32 MSB product V 
Negate integer with borrow 

Negate floating-point value 

Negate integer 

Normalize floating-point value 

Reciprocal of floating point V 
Round floating-point value 

Reciprocal of square root, floating point V 
Subtract integers with borrow 

Subtract integers conditionally 

Subtract floating-point values 

Subtract reverse-integer with borrow 

Subtract reverse floating-point value 

Subtract reverse integer 


T Two- and three-operand versions 
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5.2.3 Logic Instructions 


The TMS320C3x and TMS320C4x support a complete set of logical instruc- 
tions, which are summarized in Table 5-6. 


Table 5-6. Summary of Logical Instructions 


Instruction Description *C4x Only 
AND tT Bitwise logical AND 

ANDN t Bitwise logical AND with complement 
LSH t Logical shift 

NOT Bitwise logical complement 

OR t Bitwise logical OR 

ROL Rotate left 

ROLC Rotate left through carry 

ROR Rotate right 

RORC Rotate right through carry 

TSTB t Test bit fields 

XOR t Bitwise exclusive OR 


T Two- and three-operand versions 


5.2.4 Program-Control Instructions 


The program-control instruction group consists of all of those instructions (23) 
that affect program flow. The repeat mode allows repetition of a block of code 
(RPTB) or of a single line of code (RPTS). Both standard and delayed 
(single-cycle) branching are supported. Several of the program control instruc- 
tions are capable of conditional operations. Table 5—7 lists the program control 
instructions. 


Table 5—7. Summary of Program-Control Instructions 


Instruction Description *C4x Only 
Bcond Branch conditionally (standard) 

BcondAF Branch conditionally delayed and annul if false V 
BcondAT Branch conditionally delayed and annul if true V 

BconaD Branch conditionally, delayed 

BR Branch unconditionally, standard 

BRD Branch unconditionally, delayed 

CALL Call subroutine 


CALLcond = Call subroutine conditionally 


DBcond Decrement and branch conditionally, standard 
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Table 5—7 Summary of Program-Control Instructions(Continued) 


5.2.5 


Instruction 
DBcona{D] 
IDLE 

IDLE2 

LAJ 
LAJcond 
LATcond 
LOPOWER 
MAXSPEED 
NOP 
RETIcond 
RETIconaD 
RETScond 
RPTB 
RPTBD 
RPTS 

SWI 

TRAP cond 


Description 

Decrement and branch conditionally, delayed 
Idle until interrupt 

Low-power idle 

Link and jump 

Link and jump conditional 

Link and trap conditional 

Divide clock by 16 (’C31 only) 

Restore clock to regular speed (’C31 only) 
No operation 

Return from interrupt conditionally 

Return from trap or interrupt, delayed 
Return from subroutine conditionally 
Repeat block of instructions 

Repeat block, delayed 

Repeat single instruction 

Software interrupt 

Trap conditionally 


Interlocked-Operation Instructions 


The interlocked-operations instructions — support 
communication and the use of external signals to allow for powerful 
synchronization mechanisms. They also guarantee the integrity of the 
communication and result in a high-speed operation. Table 5—8 lists the inter- 


locked-operation instructions. 


Table 5-8. Summary of Interlocked-Operation Instructions 
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Instruction 
LDFI 

LDII 

SIGI 

STFI 

STIl 


Description 

Load floating-point value, interlocked 
Load integer, interlocked 

Signal, interlocked 

Store floating-point value, interlocked 
Store integer, interlocked 


*C4x Only 


multiprocessor 
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5.2.6 Conversion Instructions 


The TMS320C40 supports two floating-point format conversion instructions: 


Table 5-9. Summary of Conversion Instructions 


Instruction Description *C4x Only 
FRIEEE Convert IEEE floating-point format to V 
2s-complement floating-point format 


TOIEEE Convert 2s-complement format to \ 
IEEE floating-point format 


5.2.7 Three-Operand Instructions 


Most instructions have only two operands; however, several arithmetic and 
logical instructions have three-operand versions. Three-operand instructions 
allow the TMS320C3x/C4x to read two operands from memory or the register 
file in a single cycle. The following differentiates the two- and three-operand 
instructions: 


_} Two-operand instructions have a single source operand (or shift count) 
and a destination operand. 


_) Three-operand instructions may have two source operands (or one 
source operand and a count operand) and a destination operand. A 
source operand may be a memory word or a register. The destination of 
a three-operand instruction is always a register. 


Table 5—10 lists the instructions that have three-operand versions. Note that 
the 3 in the mnemonic can be omitted from three-operand instructions. 
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Table 5-10. Summary of Three-Operand Instructions 


Instruction Description *C4x Only 
ADDC3 Add with carry 

ADDF3 Add floating-point values 

ADDI3 Add integers 

AND3 Bitwise logical AND 

ANDN3 Bitwise logical AND with complement 

ASH3 Arithmetic shift 

CMPF3 Compare floating-point values 

CMPI3 Compare integers 

LSH3 Logical shift 

MPYF3 Multiply floating-point values 

MPYI3 Multiply integers 

MPYSHI3 Multiply signed integer; store 32-MSB product V 
MPYUHI3 Multiply unsigned integer; store 32-MSB product V 
OR3 Bitwise logical OR 

SUBB3 Subtract integers with borrow 

SUBF3 Subtract floating-point values 

SUBI3 Subtract integers 

TSTB3 Test bit fields 

XOR3 Bitwise exclusive-OR 


5.2.8 Parallel Instructions 


Some of the TMS320 instructions can occur in pairs that will be executed in 
parallel. Table 5-11 lists the valid instruction pairs. These parallel 
instructions allow: 


(} Parallel loading of register, 

_j Parallel arithmetic operations, and 

(1 Arithmetic or logical instructions that can be used in parallel with a store 
instruction. 


Each instruction in a pair is entered as a separate source statement; the sec- 
ond instruction must be preceded by two vertical bars (||). This example 
shows the syntax for parallel instructions: 


label: ADDI3 RO, *ARO,R1 ; Part 1 (label is 
; optional) 
|| STI R4,*+AR11. ; Part 2 


Note that the first instruction in the pair may have a label, but the second in- 
struction cannot have a label. 
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The assembler allows several relaxed syntax forms for parallel instructions: 


Lj 


The vertical bars can be placed in column 1 or anywhere between column 
1 and the mnemonic. Here is another example of valid syntax for parallel 
instructions: 
label: MPYI3 RO, *AR1,RO 

|| ADDI3 *AR2,R1,R2 
The instructions in a parallel instruction pair may be specified in either or- 
der. For instance, the preceding example could also be specified as: 
label: ADDI3 *AR2,R1,R2 

|| MPYI3 RO, *AR1,RO 
Alternate forms of the parallel/load and store/store instructions allow you 
to explicitly specify the execution order. These have the same syntax as 
the normal forms but the mnemonics are suffixed with “1” and “2”. For ex- 
ample, this is the normal form: 


STI RO, *AR4 7 executes second 
| | STI R1, *AR4 ; executes first 


can be written as 


STI1 RO,*AR4 ; executes first 
| | STI2 R1,*AR4 7 executes second 


If one of the instructions in a pair uses a three-operand instruction, you can 
omit the 3 for that instruction. 


MPYI3 RO,*AR1,RO canbe MPYI RO,*AR1,RO 
|| ADDI3 *AR2,R1,R2 writtenas || ADDI *AR2,R1,R2 


All commutative operations can be written in either order. For example, 


ADDI *ARO,R1,R2 canbewrittenas ADDI R1,*ARO,R2 


The third operand of a three-operand instruction specifies a destination 
register. You can omitthe third operand if it is the same as the second oper- 
and. This allows you to use three-operand instructions that look like two- 
operand instructions. For example, 


ADDI3 *ARO,R2,R2 canbe ADDI *ARO,R2 
MPYI3 *AR1,RO,RO writtenas MPYI *AR1,RO 
Instructions that can use the preceding two syntaxes include: 


ADDC3 AND3 LSH3 OR3 SUBI3 
ADDF3 ANDN3 MPYF3 SUBB3 XOR3 
ADDIS =ASH3 MPYI3 


Note that all registers are read at the beginning of the execution cycle and 
loaded atthe end of the execution cycle. If an instruction in a pair reads a regis- 
ter and another instruction writes to the same register, then the former instruc- 
tion uses the contents of the register before it is modified by the latter instruc- 
tion. 
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Table 5-117. 
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Mnemonic 
ABSF || STF 


ABS! || STI 
ADDF3 || STF 


ADDI || STI 
ANDS3 || STI 
ASH || STI 
FIX || STI 
FLOAT || STF 


FRIEEE || STF 
LDF || STF 


LDI || STI 
LSH || STI 
MPYF3 || STF 


MPYI3 || STI 
NEGF || STF 


NEG! || STI 
NOTS || STI 
OR3 || STI 
STF || STF 
STI || STI 
SUBF3 || STF 


TOIEEE || STF 
SUB3 || STI 
XOR3 || STI 


Summary of Parallel Instructions 


Parallel Arithmetic With Store Instructions 
Description 


Absolute value of a floating-point number 
and store floating-point value 


Absolute value of an integer and store integer 


Add floating-point values and store floating-point 
value 


Add integers and store integer 

Bitwise logical-AND and store integer 

Arithmetic shift and store integer 

Convert floating-point to integer and store integer 


Convert integer to floating-point value 
and store floating-point value 


Convert IEEE floating point format and store 


Load floating-point value and store floating-point 
value 


Load integer and store integer 
Logical shift and store integer 


Multiply floating-point values and store floating- 
point value 


Multiply integer and store integer 


Negate floating-point value and store floating-point 
value 


Negate integer and store integer 
Complement value and store integer 
Bitwise logical-OR value and store integer 
Store floating-point values 

Store integers 


Subtract floating-point value and store floating- 
point value 


Convert to IEEE format and store 
Subtract integer and store integer 
Bitwise exclusive-OR values and store integer 


*C4x Only 
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Table 5-11. Summary of Parallel Instructions (Continued) 


Parallel Load Instructions 


Mnemonic Description *C4x Only 
LDF || LDF Load floating-point 
LDI || LDI Load integer 


Parallel Multiply and Add/Subtract Instructions 
Mnemonic Description *C4x Only 
MPYFS || ADDF3 Multiply and add floating-point 
MPYF8 || SUBF3 Multiply and subtract floating-point 
MPYIS3 || ADDI3 Multiply and add integer 
MPYI3 || SUBI3 Multiply and subtract integer 
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5.2.9 TMS320C4x-Only Instructions 
Some of the instructions work only on the TMS320C4x. Table 5—12 lists these 


instructions. 


Table 5-12. Summary of TMS320C4x-Only Instructions 


Instruction 
BcondAF 
BcondAT 
FRIEEE 
FRIEEE||STF 
LAJ 
LAJcond 
LATcond 
LBb 
LBUb 
LDA 
LDEP 
LDHI 
LDPE 
LDPK 
LHw 
LHUw 
LWLct 
LWRct 
MBct 
MHct 
MPYSHI 
MPYSHI3 
MPYUHI 
MPYUHI3 


Description 

Branch conditionally delayed and annul if false 

Branch conditionally delayed and annul if true 

Convert from IEEE format 

Parallel FRIEEE and STF 

Link and Jump (Single-cycle subroutine call) 

Link and jump conditionally (Single-cycle subroutine call) 

Link and trap conditional delayed (delayed conditional trap) 
Load sign-extended byte 

Load unsigned byte 

Load address register (faster than LDI for select registers) 
Load integer from expansion register file to primary register file 
Load 16 MSBs with 16-bit immediate 

Load integer from primary register file to expansion register file 
Load data-page pointer immediate 

Load sign-extended half-word 

Load unsigned half-word 

Load word left-shifted (ct = no. of bytes to shift left, 1, 2, or 3) 
Load word right-shifted (ct = no. of bytes to shift right, 1, 2, or 3) 
Merge byte left-shifted (ct = no. of bytes to shift left, 1, 2, or 3) 
Merge half-word left-shifted (ct = no. of bytes to shift left) 
Multiply signed integer and produce 32 MSBs 

Multiply signed integer and produce 32 MSBs (3 operand) 
Multiply unsigned integer and produce 32 MSBs 

Multiply unsigned integer and produce 32 MSBs (3 operand) 
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Table 5-12. Summary of TMS320C4x-Only Instructions (Continued) 


Instruction Description 

RCPF Reciprocal of floating-point value 

RETIconaD Return from interrupt conditionally or trap conditionally delayed 
RPTBD Repeat block delayed 

RSQRF Reciprocal of the square root of a floating-point value 

STIK Store integer immediate value 

TOIEEE Convert to IEEE format 


TOIEEE||STF Parallel TOIEEE and STF 


5.2.10 LDP and LDPK Instructions 


The LDP (load data page pointer) and LDPK (load data page pointer, immedi- 
ate) instructions are special forms of the LDI (load integer) instruction. 


LDP enables you to load a register (usually the DP register) with the page num- 
ber of arelocatable address. A page number is represented by the eight MSBs 
of a 24-bit address. The page number is combined with the 16 LSBs of an in- 
struction word to form a direct address. 


LDP is a pseudo-op on the C4x only. If the destination register is the DP (de- 
fault value), this instruction actually generates an LDPK instruction. Other- 
wise, it generates an LDIU instruction. Since the C30 does not have an LDPK 
instruction, LDP always generates an LDIU instruction. 


LDPK allows you to load a 16-bit unsigned immediate value into the DP regis- 
ter. The value is loaded and ready for the next instruction for immediate ad- 
dressing. 


Instruction Set 5-19 


Instruction Set Summary Table 


5.3 Instruction Set Summary Table 


Syntax 


ABSF src, 


dst 


[ABSF dst] 


ABSI src,dst 


[ABSI dst] 


ADDC src,dst 


ADDC3 src2,src1,dst 


[ADDC src2,src1,dst] 


ADDF src,dst 

ADDF3 © src2,src1,dst 
[ADDF _— src2,src1,dst] 
ADDI src,dst 

ADDI3 ~ src2,src1,dst 
[ADDI src2,src1,dst] 
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Absolute Value of a Floating-Point Number 
Operation: |src| > dst 


Load the absolute value of the source operand into the destination register. 
The operands are floating-point numbers. 


Absolute Value of an Integer 
Operation: |src| > dst 


Load the absolute value of the source operand into the destination register. 
The operands are signed integers. 


Add Integers With Carry 
Operation: src + dst + C > dst 


Add the contents of the source operand, the destination register, and the carry 
bit together, and store the sum in the destination register. The operands are 
signed integers. 


Add Integers With Carry (3-Operand) 
Operation: src1 + src2 + C > dst 


Add source 1, source 2, and the carry bit together, and store the sum in the 
destination register. The operands are signed integers. 


Add Floating-Point Values 
Operation: src + dst > dst 


Add the contents of the source operand to the contents of destination register 
and store the result in the destination register. The operands are floating-point 
numbers. 


Add Floating-Point Values (3-Operand) 
Operation: src1 + src2 —> dst 


Add source 1 and source 2 together and store the sum in the destination regis- 
ter. The operands are floating-point numbers. 


Add Integers 
Operation: src + dst > dst 


Add the source operand to the contents of the destination register and store 
the sum in the destination register. The operands are signed integers. 


Add Integers (3-Operand) 


Operation: src1 + src2 — dst 


Add source 1 and source 2 together and store the sum in the destination regis- 
ter. The operands are signed integers. 


*C4x 
Only 


Syntax 


AND src,dst 
[AND src,dst] 


AND3 src2,src1,dst 


[AND src2,src1,dst] 


ANDN src, dst 


ANDN3 © src2,src1,dst 
[ANDN ~— src2,src1,dst] 


ASH count,dst 
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Description 


Bitwise Logical AND 
Operation: dst AND src > dst 


Perform a bitwise logical AND of the source operand and the destination 
register and store the result in the destination register. The operands are un- 
signed integers. 


Bitwise Logical AND (3-Operand) 
Operation: src1 AND src2 > dst 


Perform a bitwise logical AND of source 1 and source 2 and store the result 
in the destination register. All the operands are signed integers. 


Bitwise Logical AND With Complement 
Operation: dst AND ~ src => dst 


Perform a bitwise logical AND of the destination register and the bitwise log- 
ical complement (~) of the source operand, and store the result into the desti- 
nation register. Both operands are unsigned integers. 


Bitwise Logical ANDN (3-Operand) 
Operation: src1 AND ~ src2 — dst 


Perform a bitwise logical AND of source operand 1 and the bitwise logical 
complement (~) of the source operand 2, and store the result into the destina- 
tion register. All the operands are signed integers. 


Arithmetic Shift 


Operation: If count > 0 
dst << count — dst 
Else 
dst >> |count| — dst 


The seven LSBs of count are used to generate the 2s-complement shift count 
(up to 32 bits). 


If count > 0, left-shift the contents of the destination register by count. Low-ord- 
er bits are filled with Os, and high-order bits are shifted out through the carry 
bit. 


If count < 0, right-shift the contents of the destination register by the absolute 
value of count. High-order bits are sign-extended as they are right-shifted, and 
low-order bits are shifted out through the carry bit. 


If count = 0, no shift is performed and the carry bit is set to 0. 


Both operands are signed integers. 
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Syntax 


ASH3 count,src,dst 


[ASH count,src,dst] 


Bcond _ src 
[Bcond @src] 


BcondAF src 
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Description 


Arithmetic Shift (3-Operand) 


Operation: If count >0 
src << count > dst 
Else 
src >> |count| — dst 


The seven LSBs of count are used to generate the 2s-complement shift count 
(up to 32 bits). 


If count > 0, left-shift the source operand by count. Low-order bits will be filled 
with Os, and high-order bits are shifted out through the carry bit. 


If count < 0, right-shift the contents of the destination register by the absolute 
value of count. High-order bits are sign-extended as they are right-shifted, and 
low-order bits are shifted out through the carry bit. 


If count = 0, no shift is performed and the carry bit is set to 0. 


Branch Conditionally (Standard) 


Operation: If cond = true 
If src is a register, src + PC 
If src is in PC-relative mode, displacement + PC + 1 — PC 
Else, continue 


Performs a branch if the condition is true. 


If the source operand is a register, its contents are loaded into the PC. If the 
source operand is expressed in PC-relative mode, the assembler generates 
a displacement: displacement = label — (PC of branch instruction +1). The dis- 
placement is stored as a 16-bit signed integer in the 16 least significant bits 
of the branch instruction word. This displacement is added to the PC of the 
branch instruction + 1 to generate the new PC. 


The TMS320C40 provides 20 condition codes for use with this instruction. 
See the TMS320C4x User’s Guide for more information. 


Branch Conditionally Delayed and Annul if False 


Operation: If cond = true 
If src is a register, src + PC 
If src is in PC-relative mode, src + PC of branch + 3 ~ PC 
Else 
If cond is false 
annul execute phase results of next three instructions 
and continue 


If the condition is true, the instruction performs a branch and the next three 
instructions. If the condition is false, the instruction annuls the effect of the ex- 
ecute phase of the next three instructions and continues. 


If the source operand is a register, its contents are loaded into the PC. If the 
source operand is an immediate value, then the sum of the PC (of the branch 
instruction) + 3 and the src are loaded into the PC. 


The three instructions following the BcondAF instruction may not modify the 
program flow. 


Syntax 


BcondAT src 


BcondD src 
[BcondD @src] 


BR 
[BR 


BRD 
[BRD 


sic 


@src| 


sic 


@src| 
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Description 


Branch Conditionally Delayed and Annul if True 


Operation: If cond = true 
If src is a register, src - PC 
annul execute phase results of next three instructions 
If src is in PC-relative mode, src + PC of branch + 3 + PC 
annul execute phase results of next three instructions 
Else, continue 


If the condition is true, the instruction performs a branch and annuls the effect 
of the execute phase of the next three instructions. 


If the source operand is a register, its contents are loaded into the PC. If the 
source operand is an immediate value, then the sum of the PC (of the branch 
instruction) + 3 and the src are loaded into the PC. 


The three instructions following the BcondAT instruction may not modify the 
program flow. 


Branch Conditionally (Delayed) 


Operation: If cond = true 
If src is a register, src PC 
If src is in PC-relative mode, displacement + PC + 3 > PC 
Else, continue 


Performs a delayed branch that allows the three instructions after the delayed 
branch to be fetched before the condition is true if the condition is true. 


If the source operand is expressed as a register, its contents are loaded into 
the PC. If the source operand is expressed in PC-relative mode, the assem- 
bler generates a displacement: displacement = label — (PC of branch instruc- 
tion +1). The displacement is stored as a 16-bit signed integer in the 16 least 
significant bits of the branch instruction word. 


The three instructions following the BconaD instruction may not modify the 
program flow. 


Branch Unconditionally 


Operation: src + PC C3x 
PC +1+src PC C4x 


Performs an unconditional branch. The source operand is a 24-bit signed inte- 
ger for the ’C4x only (in the PC-concatenation addressing mode). The source 
operand is a 24-bit unsigned address for the ’C3x. 


Branch Unconditionally Delayed 


Operation: src + PC C3x 
PC +3+src > PC C4x 


Perform an unconditional branch. The source operand is a 24-bit signed inte- 
ger for the ’C4x only (in the PC-concatenation addressing mode). The source 
operand is a 24-bit unsigned address for the ’C3x. 
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Syntax 
CALL SIC 
[Call @src| 


CALLcond src 
[Callcond @src] 


CMPF src,dst 


CMPF3 ~ src2,src1 


[CMPF — src2,src1] 


CMPI src,dst 
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Description 


Call Subroutine 


Operation: Next PC > *(++SP) 
PC +1+src > PC C4x 
src > PC C3x 


Calls a subroutine. The next PC value is pushed onto the system stack. The 
source operand + 1 + PC (of the call) is loaded into the PC. The source oper- 
and is a 24-bit signed immediate value for the 'C4x only. The source operand 
is a 24-bit unsigned address for the ’C3x. 


Call Subroutine Conditionally 


Operation: If cond = true 
Next PC > *++SP 
If src is a register, src + PC 
If src is in PC-relative mode, displacement + PC + 1 — PC 
Else, continue 


Call a subroutine if the condition is true. 


If the source operand is expressed as a register, its contents are loaded into 
the PC. If the source operand is expressed in PC-relative mode, the assem- 
bler generates a displacement: displacement = label — (PC of branch instruc- 
tion +1). The displacement is stored as a 16-bit signed integer in the 16 LSBs 
of the branch instruction word. The displacement is added to the PC of the call 
instruction + 1 to generate the new PC. 


The TMS320C40 provides 20 condition codes for use with this instruction. 
See the TMS320C4x User’s Guide for more information. 


Compare Floating-Point Values 
Operation: dst — src 


Compare the source and destination operands by subtracting the source from 
the destination. The result of the subtraction is not stored; this is anondestruc- 
tive compare. Both operands are floating-point numbers. 


Compare Floating-Point Values (3-Operand) 


Operation: src1—src2 


Compare the source operands by subtracting source 2 from source 1. The re- 
sult of the subtraction is not stored; this is a nondestructive compare. Both op- 
erands are floating-point numbers. 


Compare Integers 
Operation: dst — src 


Compare the source and destination operands by subtracting the source from 
the destination. The result of the subtraction is not stored; this is anondestruc- 
tive compare. Both operands are integers. 


Syntax 


CMPI3 
[CMPI 


src2,src1 
src2,src1] 


DBcond ARn,src 


[DBcond ARn,@src] 


DBcondD AR»n,src 


[DBcond ARn,@src] 


FIX 
[FIX 


src,dst 
dst] 
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Description 


Compare Integers (3-Operand) 
Operation: src1 —src2 


Compare the two source operands by subtracting source 2 from source 1. The 
result of the subtraction is not stored; this is a nondestructive compare. Both 
operands are integers. 


Decrement and Branch Conditionally (Standard) 


Operation: ARn—1— ARn 
If cond = true and ARn = 0 
If src is a register, src — PC 
If src is in PC-relative mode, displacement + PC + 1 > PC 
Else, continue 


Decrement the specified auxiliary register and branch if the condition is true 
and the specified auxiliary register is not zero. (Executes in four cycles.) The 
auxiliary register is treated as a 24-bit signed integer (32 for ’C4x). 


If the source operand is expressed as a register, its contents are loaded into 
the PC. If the source operand is expressed in PC-relative mode, the assem- 
bler generates a displacement: displacement = label — (PC of branch instruc- 
tion + 1). The displacement is stored as a 16-bit signed integer in the 16 least 
significant bits of the branch instruction word. The displacement is added to 
the PC of the call instruction + 1 to generate the new PC. 


Decrement and Branch Conditionally (Delayed) 


Operation: ARn-1—ARn 
If cond = true and ARn = 0 
If src is a register, src PC 
If src is in PC-relative mode, displacement + PC + 3 ~ PC 
Else, continue 


Decrement the specified auxiliary register and branch if the condition is true 
and the specified auxiliary register is not zero. The auxiliary register is treated 
as a 24-bit signed integer (32 for ’C4x). 


If the source operand is expressed as a register, its contents are loaded into 
the PC. If the source operand is expressed in PC-relative mode, the assem- 
bler generates a displacement: displacement = label — (PC of branch instruc- 
tion + 3). The displacement is stored as a 16-bit signed integer in the 16 least 
significant bits of the branch instruction word. The displacement is added to 
the PC of the call instruction + 3 to generate the new PC. 


The three instructions following the DBconaD instruction may not modify the 
program flow. 


Convert Floating-Point Value to Integer 


Operation: fix(src) > dst 


Convert a floating-point operand to the nearest integer that is less than or 
equal to its absolute value and load the result into the destination register. 
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Syntax 


FLOAT _ src,dst 
[FLOAT dst] 


FRIEEE - src,dst 


IACK src 


IDLE 


IDLE2 
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Description 


Convert Integer to Floating-Point Value 
Operation: float(src) — dst 


Convert an integer into a floating-point value and load the result into the desti- 
nation register. 


Convert From IEEE Format 
Operation: convert src from IEEE — dst 


Convert the source operand from a IEEE floating-point format to the 2s-com- 
plement floating-point format, and store the result into the destination (exten- 
ded-precision) register. The source operand comes from memory. The con- 
verted result is stored as a single-precision floating-point number. 


Interrupt Acknowledge 


Operation: Perform a dummy read operation with IACK = 0. 
At end of dummy read, set [ACK = 1. 


Perform a dummy read operation with IACK = 0. IACK is set to 1 at the end 
of the dummy read. This instruction can be used to generate an external inter- 
rupt acknowledge. 


If the specified address is off-chip, the processor reads the data at that 
address. Then, the |ACK signal and the address can be used to signal an inter- 
rupt acknowledge to external devices. The data read by the processor is not 
used. 


Idle Until Interrupt 


Operation: 1 — ST(GIE) 
Next PC > PC 
Idle until interrupt 


Load the next PC value into the PC, and the CPU idles until an interrupt is re- 
ceived. When an interrupt is received, the contents of the PC are pushed onto 
the system stack. 


Low-power Idle (’C31, ’C40, ’C44 only) 


Operation: 1 — ST(GIE) 
Next PC > PC 
Idle until interrupt 


Performs the same function as IDLE, except that it removes the functional 
clock input from the internal device. This allows for extremely low power 
mode. The PC is incremented once, and the device remains in an idle state 
until one of the external interrupts (INTO—3) is asserted. 


Syntax 


LAJ src 


LAJcond src 


LATcond N 
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Description *C4x 


Link and Jump 


Operation: PC of LAJ + 4 > R31 (extended-precision register R11) 
src [ + 3 + PC of LAJ] ~ PC 


Performs a single-cycle subroutine call. The three instructions following the 
LAd instruction are performed. The return address (address of LAJ instruction 
+ 4) is placed in extended-precision register R11. The source operand is a 
24-bit signed integer (in the PC-concatenation addressing mode). 


The three instructions following the DBconaD instruction may not modify the 
program flow. 


Link and Jump Conditionally 


Operation: If cond = true 

If src is a register 
PC of LAJcond + 4 > extended-precision register R11 
src > PC 

If src is in PC-relative mode 
PC of LAJcond + 4 > extended-precision register R11 
src + PC of LAJ + 3 — PC 

Else, continue 


Performs a conditional single-cycle subroutine call. The three instructions fol- 
lowing the LAJcond instruction are performed. The return address (address 
of LAd instruction + 4) is placed in extended-precision register R11. 


The three instructions following the LAJcond instruction may not modify the 
program flow. 


Link and Trap Conditionally 


Operation: If cond = true 

[ST(GIE) > ST (PGIE) 
ST(CF) > ST(PCF)] 
0 > ST(GIE) 
1 — ST(CF) 
PC of LATcond + 4 > R31 (extend-precision register R11) 
trap vector N + PC 

Else, continue 


Performs a delayed conditional trap. If you nest the traps, you may have to 
save the status register before executing LATcond. 


If the condition is true: 
GIE and CF are saved in PGIE and PCF in the status register, 
all interrupts are disabled, 
the cache is frozen, 
the contents of the PC (of LATcond + 4) are placed in R31, and 
the PC is loaded with the contents of the specified trap vector (N). 
If the condition is not true, then normal execution continues. 


The three instructions following LATcond are fetched and executed. None of 
these three instructions may modify the program flow. 
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Syntax 
LBb(0,1,2,3) src,dst 


LBUb(0,1,2,3) src,dst 


LDA src,dst 


LDE src,dst 


LDEP src,dst 


LDF src,dst 


LDFcond src,dst 
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Description 


Load Byte, Signed 
Operation: sign-extended byte (0,1,2,3) of src > dst 


Sign-extend and right-shift the specified byte of the source operand, and then 
load it into the 8 LSBs of the destination register. The source operand is 
signed. 


Load Byte, Unsigned 
Operation: byte (0,1,2,3) of src > dst 


Right-shift the specified byte of the source operand and load it into the 8 LSBs 
of the destination register. The source operand is unsigned. 


Load Address Register 
Operation: src > dst 


Load the source operand into the destination register. The destination register 
may be any of these address registers: ARO—AR7, IRO, IR1, DP, BK, or SP. 
The load is finished by the end of the read phase of the pipeline; therefore, 
LDA is one cycle faster than LDI for loading these registers. All the operands 
are treated as signed integers. 


Load Floating-Point Exponent 
Operation: src(exponent) — dst(exponent) 


Load the exponent portion of a word into the exponent field of an extended- 
precision register. The operands are floating-point values. 


Load Integer From Expansion-Register File to Primary-Register File 
Operation: src > dst 


Load the source operand (from expansion-register file) into the destination 
register (from the primary-register file). The destination register is an integer. 


Load Floating-Point 


Operation: src > dst 


Load the source operand into the destination operand. Both operands are as- 
sumed to be floating-point numbers. 


Load Floating-Point, Conditionally 


Operation: If cond = true 
src — dst 
Else, dst is not changed 


If the specified condition is true, load the source operand into the destination 
operand. If the condition is false, the value is not loaded. Both operands are 
assumed to be floating-point numbers. 


Syntax 


LDFI src,dst 


LDHI src,dst 


LDI src,dst 


LDlicond src,dst 


LDII src,dst 


LDM src,dst 
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Description 


Load Floating-Point Value, Interlocked 


Operation: Signal interlocked operation 
src > dst 


Load the source operand into the destination register. An interlocked opera- 
tion is signaled over the LOCK and LLOCK pins. Only direct and indirect 
modes are allowed. The operands are floating-point values. 


Load 16 MSBs With 16-Bit Immediate 


Operation: src — 16 MSBs of dst 
0 > 16 LSBs of dst 


Load the 16-bit unsigned immediate value into the 16 MSBs of the destination 
register. Load 0 into the 16 LSBs of the destination register. The destination 
register is an integer. 


Load Integer 
Operation: src — dst 


Load the contents of the source operand into the destination register. The op- 
erands are signed integers. 


Load Integer Conditionally 


Operation: If cond = true 
src > dst 
Else, dst is not changed 


If the specified condition is true, load the contents of the source operand into 
the destination register. If the condition is false, the source operand is not 
loaded. The operands are signed integers. 


The TMS320C40 provides 20 condition codes for use with this instruction. 
See the TMS320C4x User’s Guide for more information. 


Load Integer, Interlocked 


Operation: Signal interlocked operation 
src — dst 


The source operand is loaded into the destination register, and an interlocked 
operation is signaled over the LOCK and LLOCK pins. Only direct and indirect 
modes are allowed. The operands are signed integers. 


Load Floating-Point Mantissa 
Operation: src(mantissa) > dst(mantissa) 


Load the mantissa field of the source operand into the mantissa field of an the 
destination register. The source and destination operands are floating-point 
numbers. 
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Syntax 


LDP src,dst 


LDPE src,dst 


LDPK src,dst 


LHw(0,1) src,dst 


LHUw(0,1) src,dst 


LOPOWER 
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Description 


Load Data Page Pointer 
Operation: src — DP 


LDP is an alternate form of LDI, except that LDP is always in the immediate 
addressing mode. The source operand field contains the 16 MSBs of the ab- 
solute value 32-bit source address. These 16 bits are loaded into the 16 LSBs 
of the data page pointer. 


Load Integer From Primary-Register File to Expansion-Register File 
Operation: src — dst 


Load the source operand (from the primary-register file) into the destination 
(from the expansion-register file). The destination register is an integer. 


Load Data Page Pointer Immediate 
Operation: src + DP 


Load the 16-bit unsigned immediate into the DP register. This operation is 
completed by the end of the read phase of the pipeline; thus, the value loaded 
is ready for the next instruction for direct addressing. 


Load Half-Word 


Operation: sign-extended half-word (0,1) of src — dst 


The specified half-word of the source operand is sign-extended and right- 
shifted into the 16 LSBs of the destination register. The half-word is signed. 


Load Half-Word Unsigned 
Operation: unsigned half-word (0,1) of src — dst 


The specified half-word of the source operand (unsigned) is right-shifted into 
the 16 LSBs of the destination register. The half-word is unsigned. 


Divide Clock by 16 (’C31 only) 
Operation: H1/16 > H1 


The device continues to execute instructions, but at the reduced rate of the 
CLKIN frequency divided by 16. This allows for low-power operations. See 
also MAXSPEED. 


Syntax 


LSH count,dst 


LSH3 count,src,dst 
[LSH count,src,dst] 


LWLct(0,1,2,3) src,dst 


LWRct(0,1,2,3) src,dst 
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Description 


Logical Shift 


Operation: If count > 0 
dst << count = dst 
Else, 
dst >> |count| — dst 


The seven LSBs of count are used to generate the 2s-complement shift count 
(up to 32 bits). 


If count is greater than zero, left-shift the contents of the destination register 
by count. Low-order bits are filled with Os, and high-order bits are shifted out 
through the carry bit. 


If count is less than zero, right-shift the contents of the destination register by 
the absolute value of count. High-order bits are filled with Os, and low-order 
bits are shifted out through the carry bit. 


If count is equal to zero, no shift is performed and the carry bit is set to 0. 


The count operand is a signed integer; dst is an unsigned integer. 


Logical Shift (3-Operand) 


Operation: If count > 0 
src << count > dst 
Else, 
src >> |count| > dst 


The seven LSBs of count are used to generate the 2s-complement shift count 
(up to 32 bits). 


If count is greater than zero, left-shift the source operand by count. Low-order 
bits are filled with Os, and high-order bits are shifted out through the carry bit. 
The result is stored in the destination register. 


If count is less than zero, right-shift the source operand by the absolute value 
of count. High-order bits are filled with Os, and low-order bits are shifted out 
through the carry bit. 


If count is equal to zero, no shift is performed and the carry bit is set to 0. 


The count operand is a signed integer; the source operand is an unsigned 
integer. The result is stored in the destination register. 


Load Word Left-Shifted 
Operation: src << (0,1,2,3) and merged with dst > dst 


The source operand is left-shifted the specified number of bytes and merged 
with the bytes of the destination register that are below the left-shifted LSBs 
of the source register. 


Load Word Right-Shifted 
Operation: src >> (0,1,2,3) and merged with dst > dst 


The source operandiis right-shifted the specified number of bytes and merged 
with the bytes of the destination register that are below the right-shifted LSBs 
of the source register. 
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Syntax 


MAXSPEED 


MBct(0,1,2,3) src,dst 


MHct(0,1) src,dst 


MPYF src,dst 

MPYF3 ~— src2,src1,dst 
[MPYF — src2,src1,dst] 
MPYI src,dst 

MPYI3 — src2,src1,dst 
[MPYI src2,src1,dst] 
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Description 


Restore Clock to Regular Speed (’C31 only) 
Operation: H1 —>H1 


Exits LOPOWER power—down mode. The ’LC31 resumes full-speed opera- 
tion during the read phase of this instruction. See also LOPOWER. 


Merge Byte 
Operation: 8 LSBs of src << (0,1,2,3) bytes merged with dst — dst 


The 8 LSBs of source operand are left-shifted the specified number of bytes 
and merged with the destination register. 


Merge Half-Word 
Operation: 16 LSBs of src << (0,1) half-words merged with dst > dst 


The 16 LSBs of source operand are left-shifted the specified number of half- 
words and merged with the destination register. 


Multiply Floating-Point Values 
Operation: src x dst — dst 


Multiply the source operand by the contents of the destination operand and 
store the result in the destination register. The source operand is a single-pre- 
cision floating-point number, and the destination is an extended-precision 
floating-point number. 


Multiply Floating-Point Values (3-Operand) 
Operation: src1 x src2 — dst 


Multiply source 1 by source 2 and store the result in the destination register. 
All the operands are extended-precision floating-point numbers. 


Multiply Integers 


Operation: src x dst > dst 


Multiply the source operand by the contents of the destination operand and 
store the result in the destination register. The source and destination oper- 
ands are 32-bit signed integers for the ’C4x and 24-bit signed integers for the 
*C3x. The result is a 64-bit integer. The output to the destination register is the 
32 LSBs of the product. 


Multiply Integers (3-Operand) 
Operation: src1 x src2 — dst 


Multiply source 1 by source 2 and store the result in the destination register. 
The source operands are 32-bit signed integers for the ’C4x, 24-bit signed in- 
tegers for the ’C3x. The result is a 64-bit integer. The output to the destination 
register is the 32 LSBs of the product. 


Syntax 


MPYSHI src,dst 


MPYISHIS3 src2,src1,dst 


MPYUHI src,dst 


MPYUHI3 src7, src2, dst 


NEGB 
[NEGB 


NEGF 
[NEGF 


NEGI 
[NEGI 


src,dst 
dst] 


src,dst 
dst] 


src,dst 
dst] 
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Description 


Multiply Signed Integers and Produce 32 MSBs 
Operation: dst x src > dst 


Multiply the source operand by the destination operand and store the 32 
MSBs of the result in the destination register. Both operands are 32-bit signed 
integers. The result is a 64-bit integer. The output to the destination register 
is the 32 MSBs of the product. 

Multiply Signed Integers and Produce 32 MSBs (3 Operand) 

Operation: src1 x src2 — dst 


Multiply source 1 by source 2 and store the 32 MSBs of the result in the desti- 
nation register. The source operands are 32-bit signed integers. The result is 
a 64-bit signed integer. The output to the destination register is the 32 MSBs 
of the product. 

Multiply Unsigned Integers and Produce 32 MSBs 

Operation: dst x src > dst 


Multiply the source operand by the destination operand and store the 32 
MSBs of the result in the destination register. Both operands are 32-bit un- 
signed integers. The resultis a 64-bit unsigned integer. The output to the desti- 
nation register is the 32 MSBs of the product. 

Multiply Unsigned Integers and Produce 32 MSBs, 3 Operand 
Operation: src1 x src2 — dst 


Multiply source 1 by source 2 and store the 32 MSBs of the result in the desti- 
nation register. The source operands are 32-bit unsigned integers. The result 
is a 64-bit unsigned integer. The output to the destination register is the 32 
MSBs of the product. 

Negate Integer With Borrow 

Operation: 0— src —C — dst 


Subtract the source operand from zero, subtract the carry bit from that result, 
and load the final result into the destination register. The operands are signed 
integers. 

Negate Floating-Point Value 

Operation: 0— src —> dst 

Load the difference between 0 and the source operand into the extended-pre- 
cision register. The operands are floating-point numbers. 


Negate Integer 


Operation: 0— src —> dst 


Load the difference between 0 and the source operand into the destination 
register. The operands are signed integers. 
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Syntax 


NOP 
[NOP src] 


NORM _ src,dst 
[NORM _ ast] 


NOT src,dst 
[NOT dst] 


OR src,dst 


OR3 src2,src1,dst 


[OR src2,src1,dst] 


POP ast 


POPF dst 


PUSH src 
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Description 


No Operation 


Operation: No ALU or multiplier operations. 
ARn is modified if src is specified in indirect mode. 


If the source operand is specified in the indirect mode, the specified address- 
ing operation is performed and a dummy memory read occurs. If the source 
operand is omitted, no operation is performed. 


Normalize Floating-Point Value 
Operation: normalize(src) > dst 


Normalize a floating-point number and load the result into an extended-preci- 
sion register. 


Bitwise Logical Complement 
Operation: ~src > dst 


Load the bitwise logical complement (~) of the source operand into the desti- 
nation register. The operands are unsigned integers. 


Bitwise Logical OR 
Operation: dst OR src —> dst 


Load the bitwise logical OR between the source and the destination into the 
destination register. The operands are unsigned integers. 


Bitwise Logical OR (3-Operand) 


Operation: src1 OR src2 — dst 


Load the bitwise logical OR between source 1 and source 2 into the destina- 
tion register. The operands are unsigned integers. 


Pop Integer From Stack 
Operation: *SP-- > dst 


Pop the contents of the top of the system stack into the destination register. 
The top of the stack is an integer. 


Pop Floating-Point Value From Stack 
Operation: *SP-- > dst 


Pop the contents of the top of the system stack into the destination register. 
The top of the stack is a floating-point number. 


Push Integer Onto Stack 
Operation: src > *++SP 


Push the contents of the source register onto the top of the system stack. The 
value pushed on the stack is a signed integer. 


Syntax 
PUSHF src 


RCPF src,dst 


RETlcond 


RETIcondD 


RETScond 
[RETS] 


RND src,dst 
[RND dst] 
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Description 


Push Floating-Point Value on Stack 
Operation: src > *++SP 


Push the contents of an extended-precision register onto the top of the system 
stack. The value pushed on the stack is a floating-point number. 


Reciprocal Floating-Point Value 
Operation: 16-bit reciprocal of src — dst 


Load the 16-bit approximation of the reciprocal of the source operand into the 
destination register. Both operands are floating-point numbers. 


Return From Interrupt Conditionally or Trap Conditionally 


Operation: If cond = true 
*(SP--) > PC 
ST(PGIE) — ST(GIE) 
ST(PCF) — ST(CF) 
Else, continue 


Performs a return from an interrupt or a trap. If the condition is true, pop the 
top of the stack to the PC, copy GIE to PGIE, and copy CF to PCF. If the condi- 
tion is false, continue normal operation. 


Return From Interrupt Conditionally or Trap Conditionally Delayed 


Operation: If cond = true 
*(SP--) > PC 
ST(PGIE) — ST(GIE) 
ST(PCF) — ST(CF) 
Else, continue 


Performs a delayed return from an interrupt or a trap. If the condition is true, 
pop the top of the stack to the PC, copy GIE to PGIE, and copy CF to PCF. 
Because this is a delayed return, the three instructions following RETIcondD 
are fetched and executed. If the condition is false, continue normal operation. 


The three instructions following the RETIcondD instruction may not modify 
the program flow. 


Return From Subroutine Conditionally 


Operation: If cond = true 
*SP-- > PC 
Else, continue 


Perform a conditional return. If the condition is true, pop the top of the system 
stack into the PC. 


The TMS320C40 provides 20 condition codes for use with this instruction. 
See the TMS320C4x User’s Guide for more information. 


Round Floating-Point Value 
Operation: round(src) — dst 


Round the source operand to the nearest single-precision floating-point num- 
ber and load it into an extended-precision destination register. 
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Syntax 
ROL ast 


ROLC ast 


ROR ast 


RORC ast 


RPTB src 
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Description 


Rotate Left 
Operation: dst is left-rotated 1 bit — dst 


Rotate the contents of the destination register left one bit and store the result 
back into the destination register. The carry bit is set to the original value of 
the MSB. 


Rotate Left Through Carry 
Operation: dst is left-rotated 1 bit through carry — dst 


Rotate the contents of the destination register left one bit through the carry bit 
and store the result back into the destination register. The carry bit is set to 
the original value of the MSB, and the new LSB value is set to the original value 
of the carry bit. 


Rotate Right 
Operation: dst is right-rotated 1 bit through carry bit — dst 


Rotate the contents of the destination register right one bit and store the result 
back into the destination register. The carry bit is set to the original value of 
the LSB. 


Rotate Right Through Carry 


Operation: dst is right-rotated 1 bit through carry — dst 


Rotate the contents of the destination register right one bit through the carry 
bit and store the result back into the destination register. The carry bit is set 
to the original value of the LSB, and the new MSB value is set to the original 
value of the carry bit. 


Repeat Block of Instructions 


Operation: If src is an immediate value 
src+PC+1—>RE 
Else if src is a register 
src — RE 
1 > ST(RM) 
next PC > RS 


Repeats a block of instructions a number of times without penalty for looping. 
Activates the block-repeat mode for updating the PC. The source operand can 
be a 24-bit immediate value or a 32-bit register that is loaded into the repeat 
end address (RE) register. The RM (repeat mode) status bit is set to 1, and 
the address of the next instruction is loaded into the repeat start address (RS) 
register. 


Syntax 


RPTBD src 


RPTS src 


RSQRF src,dst 


SIGI src,dst 
SIGI 


*C4x 
*C3x 
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Description 


Repeat Block of Instructions Delayed 


Operation: if src is an immediate value 
src+PC+1—RE 
else if src is a register 
src — RE 
1 > ST(RM) 
PC of RPTBD +4 — RS 


Repeats a block of instructions a number of times without penalty for looping. 
Activates the block-repeat mode for updating the PC. The source operand can 
be a 24-bit immediate value or a 32-bit register that is loaded into the repeat 
end address (RE) register. The RM (repeat mode) status bit is set to 1, and 
the address of the next instruction + 3 is loaded into the repeat start address 
(RS) register. 


The three instructions following the RPTBD instruction may not modify the 
program flow, nor may the instructions be part of the block that is repeated and 
cannot modify RC, RS, or RE. 


Repeat Single Instruction 


Operation: src > RC 
1 > ST(RM) 
138 
next PC > RS 
next PC — RE 


Repeat a single instruction by the number in the RC (repeat counter) register. 
The source operand is loaded into the RC (repeat counter) register. A one is 
written into the repeat mode bit (RM) of the status register (ST) A one is also 
written into the repeat single bit (S). This indicates that the program fetches 
are to be performed only from the instruction register. The next PC is loaded 
into the repeat start address (RS) and repeat end address (RE) registers. 


Reciprocal of Square Root Floating-Point 


Operation: 16-bit reciprocal of the square root of src > dst 


Load the 16-bit approximation of the reciprocal of the square root of the source 
operand into the destination register. The source operandis positive; the oper- 
ation for negative inputs is undefined. Both operands are floating-point num- 
bers. 


Signal and Read Integer Interlocked 


Operation: LOCK (or LLOCK) pin brought low 
src > dst 
LOCK (or LLOCK) pin brought high 


An interlocked operation is signaled using the appropriate bus-lock signal 
(LOCK or LLOCK) if and only if external memory access is performed. After 
the read, the bus-lock signal is deasserted. If an internal memory access is 
performed, SIGI will perform the read but will not assert a bus-lock signal. The 
source and destination operands are signed integers. Operation differs for 
’°C3x. Refer to TMS320C3x User's Guide. 
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Syntax 


STF src,dst 


STFI src,dst 


STI src,dst 


STII src,dst 


STIK src,dst 


SUBB src,dst 


SUBB3 © src2,src1,dst 


[SUBB — src2,src1,dst] 
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Description 


Store Floating-Point Value 
Operation: src > dst 


Store the contents of the source register into the destination memory location. 
The operands are floating-point values. 


Store Floating-Point Value, Interlocked 


Operation: src — dst 
Signal end of interlocked operation 


Store the contents of the source register into the destination memory location. 
An interlocked operation is signaled over LOCK and LLOCK. The operands 
are floating-point values. 


Store Integer 
Operation: src > dst 


Store the contents of the source register into the destination memory location. 
The operands are signed integers. 


Store Integer, Interlocked 


Operation: src — dst 
Signal end of interlocked operation 


The contents of the source operand are stored at the destination. An inter- 
locked operation is signaled over LOCK and LLOCK. The operands are 
signed integers. 


Store Integer Immediate Value 


Operation: src > dst 


Store the 5-bit signed integer (in the source register field) into the destination 
memory location. The operands are signed integers. 


Subtract Integers With Borrow 
Operation: dst — src —C — dst 


Subtract the source operand from the destination register, subtract the carry 
bit from the result, and load the final result into the destination register. The 
operands are signed integers. 


Subtract Integers With Borrow (3-Operand) 
Operation: src1 —src2 —C — dst 


Subtract source operand 2 from source operand 1, subtract the carry bit from 
the result, and load the final result into the destination register. The operands 
are signed integers. 


Syntax 
SUBC src,dst 


SUBF src,dst 


SUBF3 © src2,src1,dst 
[SUBF = src2,src1,dst] 


SUBI src,dst 


SUBI3 — src2.src1,dst 


[SUBI src2,src1,dst] 


SUBRB src,dst 


SUBRF src,dst 
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Description 


Subtract Integers Conditionally 


Operation: If dst-—src > 0 
(dst — src << 1) OR 1 > dst 
Else 
dst <<1 — dst 


If the difference between the destination and the source operands is greater 
than or equal to 0, then shift the difference left 1 bit, set the LSB to 1, and store 
the result in the destination register. 


If the difference between the destination and source is less than zero, left-shift 
the contents of the destination register by 1 bit. 


The operands are signed integers. 
Subtract Floating-Point Values 
Operation: dst — src > dst 


Subtract the source operand from the contents of the destination operand and 
store the result in the destination register. Both operands are floating-point 
numbers. 


Subtract Floating-Point Values (3-Operand) 
Operation: src1 — src2— dst 


Subtract source 2 from source 1 and store the result in the destination register. 
All the operands are floating-point numbers. 


Subtract Integers 
Operation: dst — src — dst 


Subtract the source operand from the contents of the destination register and 
store the result in the destination register. Both operands are signed integers. 


Subtract Integers (3-Operand) 
Operation: src1 —src2 — dst 


Subtract source 2 from source 1 and store the result in the destination register. 
All the operands are signed integers. 


Subtract Reverse Integer With Borrow 


Operation: src — dst — C > dst 


Subtract the destination register from the source register, subtract the carry 
bit from the result, and load the final result into the destination register. Both 
operands are signed integers. 


Subtract Reverse Floating-Point Value 
Operation: src — dst — dst 


Subtract the contents of the destination register from the source operand and 
store the result into the destination register. Both operands are floating-point 
numbers. 


Instruction Set 
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Instruction Set Summary Table 


Syntax 
SUBRI src,dst 


SWI 


TOIEEE src,dst 


TRAP cond N 
[TRAP N 


TSTB src,dst 
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Description 


Subtract Reverse Integer 
Operation: src — dst — dst 


Subtract the contents of the destination register from the source operand and 
store the result into the destination register. Both operands are signed inte- 
gers. 


Software Interrupt 
Operation: Perform emulator interrupt sequence. 


Performs an emulator interrupt. This is a reserved instruction and should not 
be used in normal programming. 


Convert To IEEE Format 
Operation: convert src to IEEE — dst 


Convert the source operand (single-precision floating-point) from 2s-comple- 
ment floating-point format to IEEE floating-point format, and store the result 
into the 32 MSBs of the destination register. You can use STF to store the re- 
sult in memory. 


Trap Conditionally 


Operation: if condis true 
[ST(GIE) > ST (PGIE) 
ST(CF) — ST(PCF)] 
0 > ST(GIE) 
1 > ST(CF) 
next PC > *(++SP) 
trap vector N > PC 

Else, continue 


Performs a conditional trap. If you nest the traps, you may have to save the 
status register before executing TRAPcond N. 


If the condition is true: 
GIE and CF are saved in PGIE and PCF in the status register, 
all interrupts are disabled, 
the cache is frozen, 
the contents of the PC are pushed on the system stack, and 
PC is loaded with the contents of the specified trap vector (N). 
If the condition is false, then continue normal operation. 


Test Bit Fields 


Operation: dst AND src 


Perform a bitwise logical AND of the source and destination and set the appro- 
priate flags on the result. This is a nondestructive compare; the results of the 
compare are not stored. The operands are unsigned integers. 


Syntax 

TSTB3 — srci1,src2 
[TSTB src1,src2] 
XOR src,dst 

XOR3 src2,src1,dst 
[XOR src2,src1,dst] 


Instruction Set Summary 


Description 


Test Bit Fields (3-Operand) 
Operation: src1 AND src2 


Perform a bitwise logical AND of source 1 and source 2 and set the appropri- 
ate flags on the result. This is a nondestructive compare; the results of the 
compare are not stored. The source operands are signed integers. 


Bitwise Exclusive OR 


Operation: dst XOR src > dst 


Perform a bitwise exclusive OR of the source and destination operands and 
store the result in the destination register. The operand are unsigned integers. 


Bitwise Exclusive OR (3-Operand) 


Operation: src1 XOR src2 — dst 


Perform a bitwise exclusive OR of source 1 and source 2 and store the result 
in the destination register. The source operands are signed integers. 


Instruction Set 


Table 
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Macro Language 


TMS320C3x/C4x assembler supports a macro language that enables you 


to create your own “instructions”. This is especially useful when a program 
executes a particular task several times. The macro language enables you to 
do the following: 


OOOO 


Define your own macros and redefine existing macros, 
Simplify long or complicated assembly code, 

Access macro libraries created with the archiver, 

Define conditional and repeatable blocks within a macro, 
Manipulate strings within a macro, and 

Control expansion listing. 


This chapter discusses the following topics: 


Topic Page 
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6.3 Macro Parameters/Substitution Symbols ...............2++020055 6-5] 
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6.5 Using Conditional Assembly in Macros ............0.e0ceeeeees 
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6.7 Producing Messages in Macros ............00ceeeeeeee eee eeeee 
6.8 Formatting the Output Listing ................ceceeeeeeeeeeeees 
6.9 Using Recursive and Nested Macros .............+22+020eee0es 
6.10 Macro Directives Summary .......... 0.0: cece cece eee eee 6-29] 
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Using Macros 


6.1 Using Macros 


Programs often contain routines that are executed several times. Instead of 
repeating the source statements for a routine, you can define the routine as 
a macro, then call the macro in the places where you would normally repeat 
the routine. This simplifies and shortens your source program. 


If you want to call a macro several times, but with different data each time, you 
can assign parameters to a macro. This enables you to pass different informa- 
tion to the macro each time you call it. The macro language supports a special 
symbol called a substitution symbol, which is used for macro parameters. 
In this chapter, we use the terms macro parameters and substitution symbols 
interchangeably. 


Using a macro is a three-step process. 


Step 1: Define the macro. You must define macros before you can use them 
in your program. There are two methods for defining macros: 


_j} Macros can be defined at the beginning of a source file or in an 
.include/.copy file. Refer to Section 6.2 for more information. 


(J Macros can also be defined in a macro library. A macro library 
is acollection of files in archive format, created by the archiver. 
Each member of the archive file (macro library) may contain one 
macro definition corresponding to the member name. You can 
access a macro library by using the .mlib directive. Macro li- 
braries are discussed in Section 6.4 on page 6-13. 


Step 2: Call the macro. After you have defined a macro, you can call it by 
using the macro name as an opcode in the source program. This is 
referred to as a macro call. 


Step 3: Expand the macro. The assembler expands your macros when the 
source program calls them. During expansion, the assembler 
passes arguments by variable to the macro parameters, replaces 
the macro call statement with the macro definition, then assembles 
the source code. By default, the macro expansions are printed in the 
listing file. You can turn off expansion listing by using the .mnolist 
directive. For more information, refer to Section 6.8 on page 6-19. 


When the assembler encounters a macro definition, it places the macro name 
in the opcode table. This redefines any previously defined macro, library entry, 
directive, or instruction mnemonic that has the same name as the encountered 
macro. This allows you to expand the functions of directives and instructions, 
as well as add new instructions. 


Defining Macros 


6.2 Defining Macros 


You can define a macro anywhere in your program, but you must define the 
macro before you can use it. Macros can be defined at the beginning of a 
source file or in an .include/.copy file; they can also be defined in a macro 
library. For more information about macro libraries, refer to Section 6.4 on 
page 6-13. 


The contents of a macro definition must be contained in the same file. Macro 
definitions can be nested, and they can call other macros. Nested macros are 
discussed in Section 6.9 on page 6-20. 


macname  .macro [parameter;] |, ... , parameter] 


model statements or macro directives 
[-mexit] 


.endm 


macname names the macro. You must place the name in the 
source statement’s label field. Only the first 32 
characters of a macro name are significant. The 
assembler places the macro name in the internal 
opcode table, replacing any instruction or previous 
macro definition with the same name. 


.-macro is a directive that identifies the source statement as 
the first line of a macro definition. You must place 
.macro in the opcode field. 


[parameters] are optional substitution symbols that appear as 
operands for the .macro directive. Parameters are 
discussed in Section 6.3, page 6-5. 


model statements are instructions or assembler directives that are 
executed each time the macro is called. 

macro directives are used to control macro expansion. 

[-mexit] functions as a “goto .endm”. The .mexit directive is 


useful when error testing confirms that macro ex- 
pansion will fail. 


.endm terminates the macro definition. 
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Defining Macros 


The following example shows the definition, call, and expansion of a macro. 


Example 6—1. Macro Definition, Call, and Expansion 
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Macro Definition: The following code defines a macro, add4, with 4 parame- 
ters: 


6 ADD4 . MACRO pl, p2, p3, p4 ; macro definition 


! add4 pl, p2, p3, p4 

! pd pl + p2 + p3 + p4 
! 

! 


- 
8 
9 


requires RO 


a ek 


4 


LDI p4, RO 
pl, RO 
ADDI p2, RO 
ADDI p3, RO 
STI RO, p4 


RR EF +t 


\ 
DIHDUUBRWNHEO 
> 
iw) 
iw) 

H 


4 


rey 
ie) 


. ENDM 
Macro Call: The following code calls the ADD4 macro with 4 arguments: 
22 00000000 ADD4 @11,@12,@13,@14 ; macro invocation 


Macro Expansion: The following code shows the substitution of the macro 
definition for the macro call. The assembler passes the arguments (supplied 
in the macro call) by variable to the parameters (substitution symbols). 


1 00000000 08200003- LDI @14,R0 
1 00000001 02200000- ADDI @11,R0 
1 00000002 02200001- ADDI @12,R0 
1 00000003 02200002- ADDI @13,R0 
1 00000004 15200003- SLL RO, @14 


If you want to include comments with your macro definition but don’t want 
those comments to appear in the macro expansion, use an exclamation point 
to precede your comments. If you do want your comments to appear in the 
macro expansion, use an asterisk or semicolon. For more information about 
macro comments, refer to Section 6.7 on page 6-17. 
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6.3 Macro Parameters/Substitution Symbols 


If you want to call a macro several times, but with different data each time, you 
can assign parameters to the macro. The macro language supports a special 
symbol, called a substitution symbol, which is used for macro parameters. 


6.3.1 Substitution Symbols 


Macro parameters are substitution symbols. Substitution symbols are sym- 
bols that represent a character string. Besides being used as macro 
parameters, these symbols can also be manipulated by .asg or .eval, outside 
of macros, to equate a character string to a symbol name. 


Valid substitution symbols may be 32 characters long and must begin with a 
letter. The remainder of the symbol can be a combination of alphanumeric 
characters, underscores, and dollar signs. 


Substitution symbols used as macro parameters are local to the macro they 
are defined in. You can define up to 32 local substitution symbols (including 
substitution symbols defined with the .var directive) per macro. For more 
information about the .var directive, refer to page 6-12. 


During macro expansion, the assembler passes arguments by variable to the 
macro parameters. The character-string equivalent of each argument is 
assigned to the corresponding parameter. Parameters without corresponding 
arguments are set to the null string. If the number of arguments exceeds the 
number of parameters, the last parameter is assigned the character-string 
equivalent of all remaining arguments. 


If you pass a list of arguments to one parameter, or if you pass a comma or 
semicolon to a parameter, you must surround the arguments with quotation 
marks. 


At assembly time, the assembler first replaces the substitution symbol with its 
corresponding character string, then translates the source code into object 
code. 
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Example 6-2 shows the expansion of a macro with varying numbers of argu- 
ments. 


Example 6-2. Calling a Macro With Varying Numbers of Arguments 


Macro Definition 


Parms .macroa,b,c 


; a= ita: 

; b = :b: 

; c= :c: 
.endm 


Calling the Macro, Parms 


Parms 100,label Parms 100,label,x,y 
; a = 100 ; a = 100 
; b = label 7, b = label 
; c=" ; c= x,y 

Parms 100, , x Parms ”100,200,300"”,x,y 
; a = 100 7 a= 100,200,300 
; b=" ; b=x 
7 c=x ; czy 


Parms LLALASY oh ecalan 0 RAL CPN 


; a = "string” 
; b= x 
7 c= y 


6.3.2 Directives That Define Substitution Symbols 
You can manipulate substitution symbols with the .asg and .eval directives. 


(1 The .asg directive assigns a character string to a substitution symbol. 


The syntax of the .asg directive is: 


-asg [”|character string[’”’], substitution symbol 


The quotation marks are optional. If there are no quotation marks, the 
assembler reads characters up to the first comma and removes leading 
and trailing blanks. In either case, a character string is read and assigned 
to the substitution symbol. 
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Example 6-3 shows character strings being assigned to substitution symbols. 


Example 6—3. Using the .asg Directive 


-asg Rl, RETURN ; veturn register 
-asg IRO, INDEXO ; index register 
-asg """Version 4.0””", version 

-asg "pl, p2, p3”, list 


_) The .eval directive performs arithmetic on numeric substitution symbols. 


The syntax of the .eval directive is: 


-.eval well-defined expression, substitution symbol 


The .eval directive evaluates the expression and assigns the string value 
of the result to the substitution symbol. Ifthe expression is not well defined, 
the assembler generates an error and assigns the null string to the symbol. 


Example 6—4 shows arithmetic being performed on substitution symbols. 


Example 6—4. Using the .eval Directive 


.asg 1,counter 

. loop 100 

.word counter 

.eval counter + 1,counter 
.endloop 


In Example 6-4, the .asg directive could be replaced with the .eval directive 
(.eval 1, counter) without changing the output. In simple cases like this, 
you can use .eval and .asg interchangeably. However, if you want to calculate 
a value from an expression, you must use the .eval directive. 


The .asg directive only assigns a character string to a substitution symbol, 
while the .eval directive evaluates an expression and then assigns the charac- 
ter string equivalent to a substitution symbol. 


6.3.3 Built-In Substitution Functions 


The following built-in substitution symbol functions enable you to make deci- 
sions based on the string value of substitution symbols. These functions al- 
ways return a value, and they can be used in expressions. Built-in substitution 
symbol functions are especially useful in conditional assembly expressions. 
Parameters to these functions are substitution symbols or character-string 
constants. 
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In Table 6-1, aand b are parameters that represent substitution symbols or 
character string constants. The term string, used below, refers to the string 
value of the parameter. 


Table 6—1. Function Definitions 


Function Return Value 

$symlen(a) length of string a 
< Oifa< b Oifa= b 

$symcmp(a,b) > Oifa> b 

$firstch(a,ch) index of the first occurrence of character constant ch 
in string a 

$lastch(a,ch) index of the last occurrence of character constant ch 
in string a 

$isdefed (a) 1 if string ais defined in the symbol table 


0 if string ais not defined in the symbol table 


$ismember (a,b) top member of list bis assigned to string a 
0 if bis a null string 


$iscons(a) 1 if string ais a binary constant 
2 if string ais an octal constant 
3 if string ais a hexadecimal constant 
4 if string ais a character constant 
5 if string ais a decimal constant 


$isname(a) 1 if string ais a valid symbol name 
0 if string ais not a valid symbol name 


$isreg (a) 1 if string ais a valid predefined register name 
0 if string ais not a valid predefined register name 


Example 6-5 shows built-in substitution symbol functions. 


Example 6—5. Using Built-In Substitution Symbol Functions to Redefine an Instruction 


PUSHX .MACRO list 

! 

! Push more than one item 

! Sismember removes the first item in the list 


-var item 

. Loop 

.break ($ismember (item, list) = 0) 
PUSH item 

-endloop 

. ENDM 
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6.3.4 Recursive Substitution Symbols 


When the assembler encounters a substitution symbol, it attempts to 
substitute the corresponding character string. If that string is also a substitution 
symbol, the assembler performs substitution again. The assembler continues 
doing this until it encounters a token that is not a substitution symbol or until 
it encounters a substitution symbol that it has already encountered during this 
evaluation. 


In Example 6-6, the x is substituted for z; z is substituted for y; and y is 
substituted for x. The assembler recognizes this as infinite recursion and 
ceases substitution. 


Example 6—6. Recursive Substitution 


-asg "x"”,z ; declare z and assign z = "x" 
-asg "z",y ; declare y and assign y = "2" 
-asg "y”,x ; declare x and assign x = "y” 
add x ; recursive expansion 


6.3.5 Forced Substitution 


In some cases, substitution symbols are not recognizable to the assembler. 
The forced substitution operator, which is a set of colons, enables you to force 
the substitution of a symbol’s character string. Simply surround a symbol with 
colons to force the substitution. Do not include any spaces between the colons 
and the symbol. 


The syntax for the forced substitution operator is: 


The assembler expands substitution symbols surrounded by colons before it 
expands any other substitution symbols. 


You can use the forced substitution operator only inside macros, and you 
cannot nest a forced substitution operator within another forced substitution 
operator. 
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Example 6—7. Using the Forced Substitution Operator 


force .macrox 
.asg 0,xX 
-loop 8 ;.loop/.endloop are discussed 
7on page 6-14 
AUX:x: .set x 
eval xt+l,x 
-endloop 
.endm 


The force macro would generate the following source code: 


AUX0O -set 0 
AUX1 .set 1 


AUX7 .set 7 


6.3.6 Accessing Individual Characters of Subscripted Substitution Symbols 


In a macro, you can access the individual characters (substrings) of a 
substitution symbol with subscripted substitution symbols. You must use the 
forced substitution operator for clarity. You can access substrings in two ways. 


(J :symbol (well-defined expression): 


This method of subscripting evaluates to a character string with one char- 
acter. 


J) :symbol (well-defined expression, , well-defined expressions): 


In this method, expression; represents the substring’s starting position, 
and expressions represents the substring’s length. You can specify 
exactly where to begin subscripting and the exact length of the resulting 
character string. The index of substring characters begins with 1, not 0. 


Example 6-8 and Example 6—9 show built-in substitution symbol functions 
used with subscripted substitution symbols. 
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Example 6—8. Using Subscripted Substitution Symbols 


MODE -MACROin, out 
! 


! Parse addressing mode 


oat (Ssymemp (“:in(1):", “*”) = 0) 
-asg “IND”, out 
-elseif (Ssymemp(":in(1):”, "@”) = 0) 


-asg “DIR”, out 
.elseif Sisreg(in) 

-asg “REG”, out 
.elseif Sisname (in) 

-asg “DIR”, out 
.endif 


. ENDM 
Invocation of MODE: 


-asg “NONE”, type 
MODE *+ar7,type 


In Example 6-8, subscripted substitution symbols are used to determine the 
addressing mode of a macro parameter. 


Example 6—9. Using Subscripted Substitution Symbols to Find Substrings 


substr -macro start, strgl,strg2,pos 
.var lenl, len2,i,tmp 
if Ssymlen(start) = 0 
.eval start,1 
.endif 
-eval 0,pos 
-eval Ls a 
.eval Ssymlen(strgl),lenl 
.eval Ssymlen(strg2),len2 
. loop 
. break i = (len2 - lenl + 1) 
.asg "sstrg2(i,lenl):”,tmp 
.if Ssymemp(strgl,tmp) = 0 
.eval i,pos 
- break 
.else 
.eval Bu EL 
.endif 
-endloop 
.endm 
.asg 0,pos 
-asg "“arl ar2 ar3 ar4”,regs 
substr 1,”ar2”,regs,pos 
.word pos ; pos has value 5 
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In Example 6-9, the subscripted substitution symbol is used to find a substring 
strg? beginning at position startin the string strg2. The position of the substring 
sirg1 is assigned to the substitution symbol pos. 


6.3.7 Substitution Symbols as Local Variables in Macros 


If you want to use substitution symbols as local variables within a macro, you 
can use the .var directive to define up to 32 local macro substitution symbols 
(including parameters) per macro. The .var directive creates temporary sub- 
stitution symbols with the initial value of the null string. These symbols are not 
passed in as parameters, and, after expansion, these symbols are lost. 


Var sym, [,symo] ... LsyMp] 


var sym, [symp]... Lsympy] 


The .var directive is used in Example 6-9. 
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6.4 Macro Libraries 


One of the ways you can define macros is in a macro library. A macro library 
is acollection of files that contain macro definitions. You must use the archiver 
to collect these files, or members, into a single file (called an archive). Each 
member of a macro library contains one macro definition. The files in a macro 
library must be unassembled source files. The macro name and the member 
name must be the same, and the macro filename’s extension must be .asm. 


For example, 

Macro Name Filename in Macro Library 
simple simple.asm 

mode mode.asm 


You can access the macro library by using the .mlib assembler directive. 
-mlib macro library filename 


When the assembler encounters an .mlib directive, it opens the library and 
creates a table of its contents. The assembler enters the names of the 
individual members within the library into the opcode tables as library entries; 
this redefines any existing opcodes or macros that have the same name. If one 
of these macros is called, the assembler extracts the entry from the library and 
loads it into the macro table. The assembler expands the library entry in the 
same manner as other macros. You can control the listing of library entry ex- 
pansions with the .mlist directive. For more information about the .mlist 
directive, refer to Section 6.8 on page 6-19. Only macros that are actually 
called from the library are extracted, and they are extracted only once. For 
more information about the .mlib directive, refer to page 4-53. 


You can create a macro library with the archiver by simply including the desired 
files in an archive. A macro library is no different from any other archive, except 
that the assembler expects the macro library to contain macro definitions. The 
assembler expects only macro definitions in a macro library; putting object 
code or miscellaneous source files into the library may produce undesirable 
effects. 


Macro Language 6-13 


Using Conditional Assembly in Macros 


6.5 Using Conditional Assembly in Macros 


The conditional assembly directives are .if/.elseif/.else/.endif and 
-loop/.break/.endloop. They can be nested within each other up to 32 levels 
deep. The format of a conditional block is 


.if well-defined expression 
code block to execute when the .if expression is true (nonzero) 
[elseif well-defined expression] 


code block to execute when the if expression is false and the .elseif 
expression is true (nonzero) 


[else] 


code block to execute when the .if expression and the _ .elseif 
expression are false (zero) 


endif 


The .elseif and .else directives are optional, and they can be used more than 
once within a conditional assembly code block. When they are omitted, and 
when the .if expression is false (zero), the assembler continues to the code 
following the .endif directive. 


The .loop/.break/.endloop directives enable you to assemble a code block 
repeatedly. The format of a repeatable block is 


-loop [well-defined expression] 
code block to repeatedly assemble 
[.break [well-defined expression]] 


continue to repeatedly assemble when the .break expression is false 
(zero) 


-endloop 


code block to execute when the .break expression is true (nonzero) 
or when the .break expression is omitted and the loop count equals 
expression. 


The .loop directive’s optional expression evaluates to the loop count. If the 
expression is omitted, the loop count defaults to 1024, unless the assembler 
encounters a .break directive. 


The .break directive and its expression are optional. If the expression evalu- 
ates to false, the loop continues. The assembler breaks the loop when the 
.break expression evaluates to true or when the .break expression is omitted 
and the loop count equals expression. When the loop is broken, the assembler 
continues with the code after the .endloop directive. 


Using Conditional Assembly in Macros 


The following examples show the .loop/.break/.endloop directives, properly 
nested conditional assembly directives, and built-in substitution symbol func- 
tions used in a conditional assembly code block. 


Example 6—10. Using the .loop/.break/.endloop Directives 


.asg 1x 
. Loop ; “infinite” 


-break (x == 10) ; if x == 10, quit loop/break with 
“ expression 


-eval xtl,x 
-endloop 


Example 6—11. Nested Conditional Assembly Directives 


.asg 1,x 
. Loop ; “infinite” 


-if (x == 10); if x == 10 quit loop 
. break ; force break 
.endif 


.eval x+1,x 
-endloop 


Example 6—12. Using the .if, .else, and .endif Directives 


ADDK3 .MACROk, src, dst 
! 


! dst dst + src +k 


.if .tms320C30 
LDIsrce, dst 

ADDI k, dst 
.else 

ADDI k, src, dst 
-endif 


- ENDM 


For more information about conditional assembly directives, refer to 
Section 6.5 on page 6-14. 
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6.6 Using Labels in Macros 


All labels in an assembly language program must be unique. This includes 
labels in macros. If amacro is expanded more than once, its labels are defined 
more than once. Defining a label more than once is illegal. The macro 
language provides a method of defining labels in macros so that the labels are 
unique. Simply follow the label with a question mark, and the assembler will 
replace the question mark with a unique number. When the macro is expand- 
ed, you will not see the unique number in the listing file. Your label will appear 
with the question mark like it did in the macro definition. The syntax for a unique 
label is: 


The following figure shows unique label generation in a macro. 


Example 6—13. Unique Labels in a Macro 


MIN.MACRO src, dst 
! 
! dst = minimum(src, dst) 
CMPI src, dst 
BHS L? 
LDI src, dst 
L? ; unique label 
. ENDM 
MINRO, R1 
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6.7 Producing Messages in Macros 


The macro language supports three directives that enable you to define your 
own assembly-time error and warning messages. These directives are espe- 
cially useful when you want to create messages specific to your needs. The 
last line of the listing file shows the error and warning counts. These counts 
alert you to problems in your code and are especially useful during debugging. 


.emsg sends error messages to the listing file. The .emsg directive gen- 
erates errors in the same manner as the assembler does, incre- 
menting the error count and preventing the assembler from pro- 
ducing an object file. 


-wmsg sends warning messages to the listing file. The .wmsg directive 
functions in the same manner as the .emsg directive but also in- 
crements the warning count. 


-mmsg sends warnings or assembly-time messages to the listing file. 
The .mmsg directive functions in the same manner as the .emsg 
directive but does not set the error count. 


Macro comments are comments that appear in the definition of the macro but 
do not show up in the expansion of the macro. An exclamation point in column 
1 identifies a macro comment. If you want your comments to appear in the 
macro expansion, precede your comment with an asterisk or semicolon. 
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Example 6—14 shows user messages in macros and macro comments that will 
not appear in the macro expansion. 


Example 6—14. Producing Messages in a Macro 


TEST . MACRO x,VY 


! [This macro checks for the correct number of parameters. 
! The macro generates an error message 
! 
! 


if x and y are not present. 


Paes (Ssymlen(x) == 0 | $symlen (y) == 0) ; Test for 
; proper input 
-emsg "ERROR - missing parameter in call to TEST” 


.endif 
Belg 


-endif 
.endm 


1 error, no warnings 
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6.8 Formatting the Output Listing 


Macros, substitution symbols, and conditional assembly directives may hide 
information. You may need to see this hidden information, so the macro lan- 
guage supports an expanded listing capability. 


By default, the assembler shows macro expansions and false conditional 
blocks in the list output file. You may want to turn this listing off or on within your 
listing file. The assembler provides three sets of directives that enable you to 
control the listing of this information. 


_J Macro and Loop Expansion Listing 


-mlist 


-.mnolist 


expands macros and .loop/.endiloop blocks. The .mlist 
directive prints to the listing all code encountered in those 
blocks. By default, the assembler behaves as if you had used 
-Miist. 


suppresses the listing expansion of macros and _ .loop/ 
.endloop blocks. 


_j) False Conditional Block Listing 


.fclist 


.fcnolist 


causes the assembler to print to the listing file all false condi- 
tional blocks that do not generate code. Conditional blocks 
appear in the listing exactly as they appear in the source 
code. By default, the assembler behaves as if you had used 
{clist. 


suppresses the listing of false conditional blocks. Only the 
code in conditional blocks that actually assembles appears in 
the listing. The .if, .elsif, .else, and .endif directives do not 
appear in the listing. 


_) Substitution Symbol Expansion Listing 


sslist 


.ssnolist 


expands substitution symbols in the listing. This is useful for 
debugging the expansion of substitution symbols. The 
expanded line appears below the actual source line. 


turns off substitution symbol expansion in the listing. By 
default, the assembler behaves as if you had used .ssnolist. 
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6.9 Using Recursive and Nested Macros 


The macro language supports recursive and nested macro calls. This means 
that you can call other macros from inside a macro definition. When you use 
nested macros, you can call different macros from your macro definition. You 
can nest macros up to 32 levels deep. When you use recursive macros, you 
call a macro from its own definition (the macro calls itself). 


When you create recursive or nested macros, you should pay close attention 
to the arguments that you pass to macro parameters because the assembler 
uses dynamic scoping for parameters. This means that the called macro uses 
the environment of the macro from which it was called. 


In the following example of nested macros, notice that the y in the in_block 
macro hides the y in the out_block macro. However, the x and z from the 
out_block macro are accessible to the in_block macro. 


Example 6-15. Using Nested Macros 
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in_block .macroy,a 
; visible parameters are y,a and 
: ‘ x,z from the calling macro 
.endm 


out_block .macrox,y,zZ 
; visible parameters are x,y,zZ 


in_block x,y; macro call with x and y as 


; arguments 


.endm 
out_block , macro call 


In the following example of recursive macros, the fact macro produces assem- 
bly code necessary to calculate the factorial of n where n is an immediate 
value. The fact macro stores that value at data memory address /oc. The fact 
macro accomplishes this by calling fact7?, which calls itself recursively. 
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Example 6—16. Using Recursive Macros 


FACT -MACROn, reg 

! 

! Compute factorial 

!on = integer constant 
! reg = dst register 


elt n-< 2 

LDI 1, reg 
-else 

LDI n, reg 
-eval n-l, n 
FACT1 

-endif 

. ENDM 


FACT1L .MACRO 
! 
! Use calling environment of FACT macro 
Belay n>l 
MPYI n, reg 
-eval n-l1,n 
FACT1 
.endif 


; RECURSIVE CALL 
. ENDM 
Invocation of FACT: 


FACT 7, RO 


Macro Language 6-21 


Macro Directives Summary 


6.10 Macro Directives Summary 


Table 6-2. Creating Macros 

Mnemonic and Syntax 
macname .macro [parameter ]...[,parameter,] 
-mlib filename 
-mexit 


.endm 


Description 


Define macro 
Identify library containing macro definitions 
Go to .endm 


End macro definition 


Table 6—3. Manipulating Substitution Symbols 


Mnemonic and Syntax 


.asg [“]character string[”], substitution symbol 
-eval well-defined expression, substitution symbol 


-var substitution symbol[,...,substitution symbol] 


Table 6-4. Conditional Assembly 


Mnemonic and Syntax 


.if well-defined expression 


-elseif well-defined expression 
.else 


endif 
.loop [well-defined expression] 


-break [well-defined expression] 


-endloop 


6-22 


Description 
Assign character string to substitution symbol 
Perform arithmetic on numeric substitution symbols 


Define local macro symbols 


Description 


Assemble code block if the condition is true 


Assemble code block if the .if condition is false and the 
.elseif condition is true. The .elseif construct is optional. 


Assemble code block if the .if condition is false. The 
.else construct is optional. 


End .if code block 
Begin repeatable assembly of a code block 


End .loop assembly if condition is true. The .break 
construct is optional. 


End .loop code block 
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Table 6-5. Producing Assembly-Time Messages 


.emsg 
.wmsg 


.mmsg 


Table 6-6. Formatting the Listing 


fclist 
.fcnolist 
-mlist 
-mnolist 
.sslist 


-ssnolist 


Mnemonic and Syntax 


Mnemonic and Syntax 


Description 


Send error message to standard output 
Send warning message to standard output 


Send assembly-time message to standard output 


Description 


Allow false conditional code block listing (default) 
Inhibit false conditional code block listing 

Allow macro listings (default) 

Inhibit macro listings 

Allow expanded substitution symbol listing 


Inhibit expanded substitution symbol listing (default) 
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Archiver Description 


The TMS320C3x/C4x archiver lets you combine several individual files into a 
single file called an archive or a library. Each file within the archive is called 
amember. Once you have created an archive, you can use the archiver to add 
more files to the library, delete or replace existing members, or extract mem- 
bers. 


You can build libraries out of any type of files. Both the assembler and the linker 
accept archive libraries as input; the assembler can use libraries that contain 
individual source files, and the linker can use libraries that contain individual 
object files. 


One of the most useful applications of the archiver is to build a library of object 
modules. For example, you could write several arithmetic routines, assemble 
them, and then use the archiver to collect the object files into a single, logical 
group. You can then specify an object library as linker input. The linker will 
search through the library and include any members that resolve external ref- 
erences. 


You can also use the archiver to build macro libraries. You can create several 
separate source files, each of which contains a single macro, and then use the 
archiver to collect these macros into a single, functional group. The .mlib 
assembler directive lets you specify the name of a macro library to the 
assembler; during the assembly process, the assembler will search the speci- 
fied library forthe macros that you call. Chapter 6 discusses macros and macro 
libraries in detail. 


These are the topics covered in this chapter: 
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7.1. Archiver Development Flow 


Figure 7—1 shows the archiver’s role in the assembly language development 
process. Both the assembler and the linker accept libraries as input. 


Figure 7-1. Archiver Development Flow 
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7.2. Invoking the Archiver 


The archiver can be invoked with command line options: 


ar30 [—]command [option] libname [filename ... filenamép] 


or with a command file: 


ar30 @command_file 


ar30 is the command that invokes the archiver. 


libname names an archive library. If you don’t specify an extension for 
libname, the archiver uses the default extension .lib. 


filename names individual member files that are associated with the 
library. If you don’t specify an extension for a filename, the 
archiver uses the default extension .obj. 


command _ tells the archiver how to manipulate the library members. A 
command can be preceded by an optional hyphen. You must 
use one of the following commands when you invoke the 
archiver, but you can use only one command per invocation. 


—a adds the specified files to the library. Note that this 
command does not replace an existing member that 
has the same name as an added file; it simply ap- 
pends new members to the end of the archive. It is 
possible to have several members with the same 
name in an archive. If you want to replace existing 
members, use the r command. 


-—d deletes the specified members from the library. 


-r replaces the specified members in the library. If you 
don’t specify any filenames, the archiver replaces the 
library members with files of the same name in the 
current directory. If the specified file is not found in the 
library, the archiver adds it instead of replacing it. 


-t prints a table of contents of the library. If you specify 
filenames, only those files are listed. If you don’t spec- 
ify any filenames, the archiver lists all library mem- 
bers. 
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—-u 


—-X 


only replaces the specified members in the library if 
the replacements are newer (have a more recent 
modification date). This command should be used in 
conjunction with the r command. 


extracts the specified files. If you don’t specify mem- 
ber names, the archiver extracts all library members. 
When the archiver extracts amember, it simply copies 
the member into the current directory; it doesnt re- 
move it from the library. 


In addition to one of the commands, you can specify the following options: 


-e 


-q 
-S 


-V 


tells the archiver not to use the default extension .obj 
for member names. 


(quiet) suppresses the banner and status messages. 
prints alist of the global symbols that are defined in the 
library. (This option is valid only with the —a, —r, and —d 
commands.) 

(verbose) provides a file-by-file description of the 


creation of a new library from an old library and its 
constituent members. 


When invoking the archiver with acommand file, the @ character must be spe- 
cified before the command file name. The command file can specify archiver 
commands, options, library names, and file names. Comments can only ap- 
pear inthe command file on a separate line beginning with a semicolon (;). The 
command file should be of the form: 


7, comments 


[command] [option] [.. . 


libname 
filename, 


filename, 


ae 
Note: Naming Library Members 


It is possible (but not desirable) for a library to contain several members with 
the same name. If you attempt to delete, replace, or extract a member, and 
the library contains more than one member with the specified name, then the 


archiver deletes, replaces, or extracts the first member with that name. 
a | 


Archiver Examples 


7.3 Archiver Examples 


Here are some examples of using the archiver. 


| 


Example 1 
This example creates a library called function.lib that contains the files 
sine.obj, cos.obj, and fit.obj. 


ar30 -a function sine cos flt 
TMS320C3x/4x Archiver Version x.xx 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
==> new archive ’function.lib’ 
==> building archive ’function.1lib’ 
Because these examples use the default extensions (.lib for the library and 
.obj for the members), it is not necessary to specify them. 


Example 2 


You can print a table of contents of function.lib with the —-t option: 


ar30 -t function 


TMS320C3x/4x Archiver Version x.xx 

Copyright (c) 1987-1997 Texas Instruments Incorporated 
FILE NAME SIZE DATE 
sine.obj 248 Mon Nov 19 01:25:44 1997 
cos.obj 248 Mon Nov 19 01:25:44 1997 
flt.obj 248 Mon Nov 19 01:25:44 1997 

Example 3 


You can explicitly specify extensions if you don’t want the archiver to use 
the default extensions; for example: 


ar30 -av function.fn sine.asm cos.asm flt.asm 


TMS320C3x/4x Archiver Version x.xx 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
==> add ’sine.asm’ 
==> add ’cos.asm’ 
==> add ’flt.asm’ 
==> building archive ’function.fn’ 


This creates a library called function.fn that contains the files sine.asm, 
cos.asm, and flt.asm. (-v is the verbose option.) 


Example 4 


If you want to add new members to the library, specify 


ar30 -as function tan.obj arctan.obj area.obj 
TMS320C3x/4x Archiver Version x.xx 
Copyright (c) 1987-1997 Texas Instruments Incorporated 
==> symbol defined: '’K2’ 
==> symbol defined: ’Rossignol’ 
==> building archive ’function.lib’ 
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Because this example doesn’t specify an extension for the libname, the 
archiver adds the files to the library called function.lib. If function.lib didn’t 
exist, the archiver would create it. (The —s option tells the archiver to list the 
global symbols that are defined in the library.) 


Example 5 


If you want to modify a member in a library, you can extract it, edit it, and 
replace it. In this example, assume there’s a library named macros.lib that 
contains the members push.asm, pop.asm, and swap.asm. 


ar30 -x macros push.asm 


The archiver makes a copy of push.asm and places it in the current direc- 
tory; itdoesn’t remove push.asm from the library, though. Now you can edit 
the extracted file. To replace the copy of push.asm that’s in the library with 
the edited copy, enter 


ar30 -r macros push.asm 
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The TMS320C3x/C4x linker creates executable modules by combining COFF 
object files. As the linker combines object files, it performs the following tasks: 


_j It allocates sections into the target system’s configured memory. 
_) It relocates symbols and sections to assign them to final addresses. 
_j It resolves undefined external references between input files. 


The linker supports a command language that controls memory configuration, 
output section definition, and address binding. The language supports 
expression assignment and evaluation and provides two powerful directives, 
MEMORY and SECTIONS, that allow you to: 


_j) Define a memory model that conforms to target system memory, 

_} Combine object file sections, 

_j Allocate sections into specific areas of memory, and 

(4 Define or redefine global symbols at link time. 
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8.1 Linker Development Flow 
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Figure 8-1 illustrates the linker’s role in the assembly language development 
process. The linker accepts several types of files as input, including object 
files, command files, libraries, and partially linked files. The linker creates an 
executable COFF object module that can be downloaded to one of several de- 
velopment tools or executed by a TMS320C3x/C4x device. 


Input files generated by TMS320C3x/C4x tools can be created on any sup- 
ported host machine and then linked by the TMS320C3x/C4x linker on a 
different machine. For example, an input file assembled by the 
TMS320C3x/C4x assembler on a PC can be linked by the TMS320C3x/C4x 
linker on a SPARCstation. If a TMS320C3x/C4x tool was not used to create 
an input file, the file must have the appropriate byte-swapping done before it 
can be linked on a different machine. 
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Figure 8-1. Linker Development Flow 
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8.2 Invoking the Linker 


The general syntax for invoking the linker is: 


Ink30 [-options] filename, ... filenamén 


Ink30 is the command that invokes the linker. 
options can appear anywhere on the command line or in a linker 


command file. (Options are discussed in Section 8.3.) 


filenames can be object files, linker command files, or archive libraries. 


The default extension for all input files is .ob/; any other exten- 
sion must be explicitly specified. The linker can determine 
whether the input file is an object file or an ASCII file that con- 
tains linker commands. The default output filename is a.out. 


There are three methods for invoking the linker: 


(1 Specify options and filenames on the command line. This example links 


two files, file1.obj and file2.obj, and uses the —o option to create an output 
module named link.out. 


1nk30 filel.obj file2.obj -o link.out 


Enter the Ink30 command with no filenames and no options; the linker will 
prompt for them: 

Command files : 

Object files [.obj] 

Output files [ ] 

Options : 


For command files, enter one or more command file names. 


For object files, enter one or more object file names. The default extension 
is .obj. Separate the filenames with spaces or commas; if the last 
character is acomma, the linker will prompt for an additional line of object 
file names. 


The output file is the name of the linker output module. This overrides any 
—o options entered with any of the other prompts. If there are no—o options 
and you do not answer this prompt, the linker will create an object file with 
the default filename of a.out. 


The options prompt is for additional options, although you can also enter 
options ina command file. Enter them with hyphens, just as you would on 
the command line. 


Put filenames and options in a linker command file. For example, assume 
the file linker.cmd contains the following lines: 
-o link.out 


filel.obj 
file2.obj 


Invoking the Linker 


Now you can invoke the linker from the command line; specify the com- 
mand file name as an input file: 


1nk30 linker.cmd 


When you use acommand file, you can also specify other options and files 
on the command line. For example, you could enter: 


ink30 -m link.map linker.cmd file3.obj 


The linker reads and processes acommand file as soon as it encounters it 
onthe commandline, so it links the files in this order: file1 .obj, file2.obj, and 
file3.obj. This example creates an output file called link.out and a map file 
called link.map. 


. ..-. . .*= =o. 26 owe ep SS 
Note: Version Number Not Required for Linker 


The linker does not have a version option to specify the target CPU. The 
target CPU type is encoded in the object files and the linker automatically 
links for the correct processor. The linker will issue an error message if you 


attempt to link object files assembled for different processors. 
| | 
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8.3 Linker Options 


Table 8-1. Linker Options Summary 
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Linker options control linking operations. They can be placed on the command 
line or in acommand file. All linker options must be preceded by a hyphen (-). 
The order in which options are specified is unimportant, except for the —| and 
—i options. Options are separated from arguments (if they have them) by an 
optional space. Table 8—1 summarizes the linker options. 


Option 


—f fill value 
-g symbol 
—-h 


—heap size 


—heap8 size 


—heap16 size 


-i dir 
-I filename t 
=m filename t 


-o filename t 


Description 


Produce an absolute, executable module. This is the default; if neither 
—a nor -r is specified, the linker acts as if —a is specified. 


Produce a relocatable, executable object module. 


The linker will not merge any duplicate symbol table entries that may ex- 
ist from multiple files. This has the effect of making the linker run faster 
at the expense of a larger COFF output file. 


Use linking conventions defined by the ROM autoinitialization model of 
the C compiler. 


Use linking conventions defined by the RAM autoinitialization model of 
the C compiler. 


Defines a global symbol that specifies the primary entry point for the out- 
put module. 


Set the default fill value for holes within output sections; fill value is a 
4-byte constant. 


Maintain the specified symbol as a global symbol, regardless of the use 
of the —h option. 


Make all global symbols static. 


Set heap size (for the C memory pool command malloc()) to size words 
and define the global symbol _SYSMEM_SIZE to specify heap size. 
Default = 1K words 


Set the size for the ’C32’s 8—-bit memory heap, and define the global 
symbol _SYSMEM8_SIZE to that value. The size and the symbol are 
used by the 8-bit memory routines. Defaults to 0 words and an unde- 
fined symbol if the 8—bit memory routines are not used. 


Set the size for the 'C32’s 16-bit memory heap, and define the global 
symbol _SYSMEM16_SIZE to that value. The size and the symbols are 
used by the 16—bit memory routines. Defaults to 0 words and an unde- 
fined symbol if the 16—bit memory routines are not used. 


Alter the library-search algorithm to look in dir before looking in the 
default location. This option must appear before the —| option. 


Name an archive library file as linker input; filenameis an archive library 
name. 


Produce a map or listing of the input and output sections, including 
holes, and place the listing in filename. 


Name the executable output module. The default filename is a.out. 


8.3.1 


-stack size 
—u symbol 
-vn 

-w 


—-X 


Linker Options 


Request a quiet run (Suppress the banner). Must be the first argument 
on the command line. 


Retain relocation entries in the output module. 


Strip symbol table information and line number entries from the output 
modules. 


Sets C system stack size to size words and defines a global symbol that 
specifies the stack size. Default = 1K words 


Place an unresolved external symbol into the output module’s symbol 
table. 


Generate version n COFF format, where nis 0, 1, or 2. The default is 
2. 


Generate a warning when an output section that is not specified with the 
SECTIONS directive is created. 


Forces rereading of libraries. Resolves “back” references. 


t The filename must follow operating system conventions 


Relocation Capability (-a and -r Options) 


One of the tasks the linker performs is relocation. Relocation is the process of 
adjusting all references to a symbol when the symbol’s address changes. The 
linker supports two options (—a and —r) that allow you to choose whether you 
will produce an absolute or a relocatable output module. Default is —a. 


(J Producing an Absolute Output Module (—a Option) 


When you use the —a option without the —r option, the linker produces an 
executable, absolute output module. Absolute files contain no relocation 
entries. Executable files contain the following: 


HM special symbols defined by the linker (Subsection 8.13.4 on page 8-53 
describes these symbols), 

Han optional header that describes information such as the program 
entry point, and 

M@ nounresolved references. 


This example links file1.obj and file2.obj and creates an absolute output 
module called a.out: 


1nk30 -a filel.obj file2.obj 
Producing a Relocatable Output Module (-r Option) 


When you use the -r option without the —a option, the linker retains reloca- 
tion entries in the output module. If the output module will be relocated (at 
loadtime) or relinked (by another linker execution), use —r to retain the relo- 
cation entries. 


The linker produces an unexecutable file when you use the —r option with- 
out —a. A file that is not executable does not contain special linker symbols 
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or an optional header. The file may contain unresolved references, but 
these references do not prevent creation of an output module. 


This example links file1.obj and file2.obj and creates a relocatable output 
module called a.out: 


1ink30 -r filel.obj file2.obj 


The output file a.out can be relinked with other object files or relocated at 
loadtime. (Linking a file that will be relinked with other files is called partial 
linking. For more information, see Section 8.15 on page 8-58.) 


Producing an Executable Relocatable Output Module (—ar) 


If you invoke the linker with both the —a and —r options, the linker produces 
an executable, relocatable object module. The output file contains the 
special linker symbols and an optional header. All symbol references are 
resolved (this is normal for a relocatable file); however, the relocation 
information is retained. 


This example links file1.obj and file2.ob; and creates an executable, 
relocatable output module called xr.out: 


1nk30 -ar filel.obj file2.obj -o xr.out 


Note that you can string the options together (Ink30 —ar) or you can enter 
them separately (Ink30 —a —r). 


Relocating or Relinking an Absolute Output Module 


The linker issues a warning message (but continues executing) when it 
encounters a file that contains no relocation or symbol table information. 
Relinking an absolute file can be successful only if each input file contains 
no information that needs to be relocated (that is, each file has no 
unresolved references and is bound to the same virtual address that it was 
bound to when the linker created it). 
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8.3.2 Disable Merge of Symbolic Debugging Information (—b Option) 


By default, the linker eliminates duplicate entries of symbolic debugging 
information. Such duplicate information is commonly generated when a C pro- 
gram is compiled for debugging. For example: 


- [ header.h ] - 
typedef struct 
{ 


<define some structure members> 
} XYZ; 


= [| £ElLoc J = 
#include “header.h” 


= || £2..e Jo = 
#include “header.h” 


When these files are compiled for debugging, both f1.obj and f2.obj will have 
symbolic debugging entries to describe type XYZ. For the final output file, only 
one set of these entries is necessary. The linker will eliminate the duplicate en- 
tries automatically. 


Using the —b option causes the linker to keep such duplicate entries. Keeping 
these entries allows the linker to run faster and use less machine memory at 
the expense of producing a larger COFF output file. 


8.3.3 C Language Options (-c and —cr Options) 


The -c and -cr options cause the linker to use linking conventions that are 
required by the TMS320C3x/C4x C compiler. 


_j The -c option tells the linker to use the ROM autoinitialization model. 


_j) The -cr option tells the linker to use the RAM autoinitialization model. 


For more information about linking C code, see Section 8.16 on page 8-60. 


8.3.4 Define an Entry Point (-e global symbol Option) 


The memory address that a program begins executing from is called the entry 
point. When a loader loads a program into target memory, the program 
counter must be initialized to the entry point; the PC then points to the begin- 
ning of the program. 


The linker can assign one of four possible values to the entry point. These val- 
ues are listed below in the order in which the linker tries to use them. If you use 
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one of the first three values, it must be an external symbol in the symbol table. 
Possible entry point values include: 


(J Thevalue specified by the -e option. The syntax is -e global symbol where 
global symboldefines the entry point and must appear as an external sym- 
bol in one of the input files to be linked. 


(1 The value of symbol _c_int00 (if present). _c_intOO must be the entry 
point if you are linking code produced by the C compiler. 


1 The value of symbol _main (if present). 


Lj Zero (default value). 


This example links file1.obj and file2.obj and sets the entry point to the value 
of the symbol begin. This symbol must be defined as external in file1 or file2. 


1nk30 -e begin filel.obj file2.obj 


8.3.5 Set Default Fill Value (-f cc Option) 


The -f option fills the holes formed within output sections or initializes uninitial- 
ized sections when they are combined with initialized sections. This allows you 
to initialize memory areas during link time without reassembling a source file. 
The argument cc is a 4-byte constant (up to eight hexadecimal digits). If you 
do not use -f, the linker uses 0 as the default fill value. 


This example fills holes with the hexadecimal value AABBCCDDh: 
1nk30 -f£ OAABBCCDDh filel.obj file2.obj 


For more information about holes, see Section 8.14 on page 8-54. 


8.3.6 Make All Global Symbols Static (-h Option) 
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The —h option makes output global symbols static. This is useful when you are 
using partial linking to link related object files into self-contained modules, then 
relinking the modules into a final system. If there are global symbols in one 
module that have the same name as global symbols in other modules, but you 
want to treat them as separate symbols, use the —h option when building the 
modules. The global symbols in the modules, which would normally be visible 
to the other modules and cause possible redefinition problems in the final link, 
are made static so that they are not visible to the other modules. 


For example, assume b1.obj, b2.obj, and b3.obj are related and reference a 
global variable GLOB. Also assume that d1.obj, d2.obj, and d3.obj are related 
and also reference a separate global variable GLOB. You can link the related 
files with the following commands: 
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1ink30 -h -r bl.obj b2.0bj b3.0bj -o bpart.out 
1ink30 -h -r dl.obj d2.0obj d3.0bj -o dpart.out 


The —h option guarantees that bpart.out and dpart.out will not have global 
symbols and therefore two distinct versions of GLOB exist. The -r option is 
used to allow bpart.out and dpart.out to retain their relocation entries. These 
two partially linked files can then be safely linked with the following command: 


1ink30 bpart.out dpart.out -o system.out 


For more information about partial linking, see Section 8.15 on page 8-58. 


8.3.7 Keep a Global Symbol (-g symbol Option) 


The —g option allows you to keep the named symbol as a non-static global 
symbol, despite the use of the —h option. This allows the sharing of specific 
symbols across multiple object files with variables of the same name. Any sym- 
bols of the specified name will be visible to all modules, and an error will result 
if the symbol has a definition in more than one file. 


8.3.8 Define Heap Size (-heap size, -heap8 size, and —heap16 size Options) 


The TMS320C3x/C4x C compiler uses an uninitialized section called .sysmem 
for the C runtime memory pool used by malloc(). You can set the size of this 
memory pool at link time by using the —heap option. Specify the size in words 
as a four byte constant immediately after the option: 


1nk30 -heap 0x4000 /* defines a 256K byte heap (.sysmem section) */ 


The linker creates the .sysmem section only if there is a .ssysmem section in 
an input file. 


The linker also creates a global symbol _| SYSMEM_SIZE and assigns it a 
value equal to the size of the heap. The default size is 1K words. 


To support the TMS320C32, the ’C3x runtime support library adds 8-bit and 
16-bit versions of the dynamic memory management functions. These func- 
tions are analogous to the 32-bit versions described in Chapter 5, Runtime 
Support Functions, of the TMS320C3x/C4x Optimizing C Compiler User’s 
Guide. The only difference is that the 8-bit and 16-bit versions allocate space 
from the .sysm8 and .sysm16 uninitialized sections rather than the .sysmem 
section. 
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void *calloc8(size_t _num, size_t _size); 
void free8(void *_ptr); 

void *malloc8(size_t _size); 

void *bmalloc8(size_t _size); 

void minit8(void); 

void *realloc8(void *_ptr, size_t _size); 


void *callocl6(size_t _num, size_t _size); 
void freel6(void *_ptr); 

void *mallocl6é(size_t _size); 

void *bmallocl6é(size_t _size); 

void minitl6(void); 

void *reallocl6(void *_ptr, size_t _size); 


The sizes of the .sysm8 and .sysm16 sections can be set by using the -heap8 
and —heap16 linker options, respectively. If the memory management func- 
tions are used but the -heap8 and —heap16 options are not used, the default 
size of each heap is 1K words. If the memory management functions are not 
used, the linker will not allocate the .sysm8 and .sysm16 sections. If the 
sections are created, the linker sets the constant heap size values in the 
_SYSMEM8_SIZE and _SYSMEM16_SIZE symbols, respectively. The 
stdlib.h header file should be included in any file that uses these new functions. 


For more information about linking C code, see Section 8.16 on page 8-60. 


8.3.9 Alter the Library Search Algorithm (-i dir & —I filename/C_DIR) 
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Usually when you want to specify a library input, you simply enter the library 
name as you would any other input filename; the linker looks for the library in 
the current directory. For example, suppose the current directory contains the 
library object.lib. Assume that this library defines symbols that are referenced 
in the file file1.obj. This is how you link the files: 


1nk30 filel.obj object.lib 


If you want to use a library that is not in the current directory, use the —I (lower- 
case “L”) linker option. The syntax for this option is -I filename. The filename 
is the name of an archive library; the space between —| and the filename is op- 
tional. 


You can augment the linker’s directory search algorithm by using the —i linker 
option or the environment variable. The linker searches for any file specified 
with —l in the following order: 


1) Itsearches directories named with the —i linker option. 

2) It searches directories named with the environment variable C_DIR. 

3) IfC_DIRis not set, it searches directories named with the assembler’s en- 
vironment variable, A_DIR. 

4) \It searches the current directory. 
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8.3.10 —i Linker Option 


DOS 
UNIX 


The -i option names an alternate directory that contains object libraries. The 
syntax for this option is —i dir. dirnames a directory that contains object librar- 
ies; the space between —i and the directory name is optional. When the linker 
is searching for object libraries named with the —I option, it searches through 
directories named with —i first. Each —i option specifies only one directory, but 
you can use several —i options per invocation. When you use the —i option to 
name an alternate directory, it must precede the -| option on the commandline 
or ina command file. 


As an example, assume that there are two archive libraries called r.lib and 
lib2.lib. The table below shows the directories that r.lib and lib2.lib reside in, 
how to set environment variable, and how to use both libraries during a link. 
Select the row for your operating system: 


Sample Pathname Invocation Command 
\c30 and \c302 ink30 fl,obyj £2,067 =i \e30 -<1\c302 -1. r. lib -1 1ib2.1liab 


/c30 and /c302 1nk30 fl.obj £2.0obj -i/c30 -i/c302 -l1 r.lib -1 lib2.1lib 


8.3.11 Environment Variable (C_DIR or A_DIR) 


DOS 


UNIX 


An environment variable is a system symbol that you define and assign a string 
to. The linker uses an environment variable named C_DIR to name alternate 
directories that contain object libraries. The command for assigning the envi- 
ronment variable is: 


Sample Pathname Invocation Command 


\dsp and \dsp2 set C_DIR=\dsp; \dsp2 


1nk30 fl.obj £2.obj -1l r.lib -1 lib2.1lib 


/dsp and /dsp2 setenv C_DIR /dsp:/dsp2 


1nk30 fl.obj £2.obj -1l r.lib -1 lib2.1lib 


The pathnames are directories that contain object libraries. Use the —| option 
on the command line or in a command file to tell the linker which libraries to 
search for. 


The assembler uses an environment variable named A_DIR to name alternate 
directories that contain copy/include files or macro libraries. If C_DIRis not set, 
the linker will search for object libraries in the directories named with A_DIR. 
Section 8.5 (page 8-21) contains more information about object libraries. 
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8.3.12 Create a Map File (-m filename Option) 


The —m option creates a link map listing and puts it in filename. This map de- 
scribes: 


(J Memory configuration 


J Input and output section allocation 


41 The addresses of external symbols after they have been relocated 


The map file contains the name of the output module and the entry point; it may 
also contain up to three tables: 


(j A table showing the memory configuration, if any nondefault memory is 
specified. 

(1 A table showing the linked addresses of each output section and the input 
sections that make up the output sections. 

41 Atable showing each external symbol and its address. This table has two 
columns: the left column contains the symbols sorted by name, and the 
right column contains the symbols sorted by address. 


This example links file 1 .obj and file2.obj and creates a map file called map.out: 
1nk30 filel.obj file2.obj -m map.out 


Section 8.17 (page 8-64) shows an example of a map file. 


8.3.13 Name an Output Module (—o filename Option) 


The linker creates an executable output module. If you do not specify a file- 
name for the output module, the linker gives it the default name a.out. If you 
want to the output module to have another name, use the —o option. The file- 
name is the new output module name. 


This example links file1.obj and file2.obj and creates an output module named 
run.out. 


1nk30 -o run.out filel.obj file2.obj 


8.3.14 Specify a Quiet Run (—q Option) 


The —q option suppresses the linker’s banner when -—q is the first option on the 
command line or ina command file. This option is useful for batch operation. 


8.3.15 Strip Symbolic Information (—s Option) 
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The —-s option creates a smaller output module by omitting symbol table infor- 
mation and line number entries. The —s option is useful for production applica- 
tions when you must create the smallest possible output module. 
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This example links file1.obj and file2.obj and places them in an output module, 
stripped of line numbers and symbol table information, named nolink. out: 


1ink30 -o nolink.out -s filel.obj file2.obj 


Note that using the —s option limits later use of a symbolic debugger and may 
prevent a file from being relinked. 


8.3.16 Define Stack Size (-stack size Option) 


The TMS320C3x/C4x C compiler uses an uninitialized section, .stack, to 
allocate space for the runtime stack. You can set the size of the .stack section 
at link time with the —stack option. Specify the size in words as a constant 
immediately after the option: 


1nk30 -stack 0x1000 /* defines a 4K stack (.stack section) */ 


If you specified a different stack size in an input section, the input section stack 
size is ignored. Any symbols defined in the input section remain valid; only the 
stack size will be different. 


When the linker defines the .stack section, it also defines a global symbol, 
__STACK_SIZE, and assigns it a value equal to the size of the section. The 
default stack size is 1K words. 


8.3.17 Introduce an Unresolved Symbol (—u symbol! Option) 


The —-u option introduces an unresolved symbol into the linker’s symbol table. 
This forces the linker to search through a library and include the module that 
defines the symbol. Note that the linker must encounter the —u option before 
it links in the member that defines the symbol. 


For example, suppose a library named sym./ib contains a member that defines 
the symbol symtab; none of the object files you are linking reference to symtab. 
However, suppose you plan to relink the output module, and you would like to 
include the library member that defines symtab in this link. Using the —u option 
as shown below forces the linker to search sym.lib for the member that defines 
symtab and to link in the member. 


1nk30 -u symtab filel.obj file2.obj sym.lib 


If you do not use —u, this member would not be included because there is no 
explicit reference to it from file1.obj or file2.obj. 
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8.3.18 COFF Format Version (—vn Option) 


The —v option allows you to specify the version of COFF used in the created 
executable. ncan be 0, 1, or 2, with 2 as the default. Previous versions of the 
tools supported only COFF version 0. This option is available for backward 
compatibility and may be removed in a future release. For a description of 
COFF, see Appendix A. 


The COFF version used to create the executable must also be supported by 
any debugger or simulator used. Note that the current simulators only support 
COFF version 0. The following debuggers support COFF versions 1 and 2: 


Debugger Version 
C3x XDS510 5.20 
C3x EVM 5.20 
C4x XDS510 2.50 


If you are not using using one of these debuggers, you must use the -v0 option 
when creating your final executable. To attain a debugger or simulator, see the 
Microprocessor Development Systems Customer Support Guide provided 
with this product. 


8.3.19 Warning Switch (—w Option) 


>> warning: 
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The —w option generates a warning message if an output section is created 
that is not explicitly specified with the SECTIONS directive. For example: 


- [ fl.asm ] - 


-sect “xsect” 
-word 0 


- [ link.cmd ] - 


n 


ECTIONS 


{ 


<no output section specifications reference xsect> 
} 
The linker creates an output section called xsect that consists of the input sec- 
tion xsect from other object files; the linker then uses the default allocation 
rules to allocate this output section into memory. If you used the —w switch 
when linking, the preceding example would generate the message: 


creating output section xsect without SECTIONS specification 
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8.3.20 Exhaustively Read Libraries (—x option) 


The linker normally reads input files, archive libraries included, only once when 
they are encountered on the command line or in the command file. When an 
archive is read, any members that resolve references to undefined symbols 
are included in the link. If an input file later references a symbol defined in a 
previously read archive library (this is called a back reference), the reference 
will not be resolved. 


You can force the linker to repeatedly reread all libraries with the —x option. The 
linker will continue to reread libraries until no more references can be resolved. 
For example, if a.lib contains a reference to a symbol defined in b.lib, and b.lib 
contains a reference to a symbol defined in a.lib, you can resolve the mutual 
dependencies by listing one of the libraries twice, as in: 


Ink30,-=laslib =1b. lib =Laslaib 


or you can force the linker to do it for you: 


1nk30 -x -la.lib -lb.lib 
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8.4 Linker Command Files 


Linker command files allow you to put linking information in a file; this is useful 
when you often invoke the linker with the same information. Linker command 
files are also useful because they allow you to use the MEMORY and 
SECTIONS directives to customize your application. You must use these di- 
rectives in a command file; you cannot use them on the command line. 
Command files are ASCII files that contain one or more of the following: 


Lj Input filenames, which specify object files, archive libraries, or other com- 
mand files. (If a command file calls another command file as input, this 
statement must be the /ast statement in the calling command file. The 
linker does not return from called command files.) 


(j Linker options, which can be used in the command file in the same manner 
that they are used on the command line. 


(1 The MEMORY and SECTIONS linker directives. The MEMORY directive 
allows you to specify the target memory configuration. The SECTIONS di- 
rective controls how sections are built and allocated. 


(1 Assignment statements, which define and assign values to global 
symbols. 


To invoke the linker with a command file, enter the Ink30 command and follow 
it with the name of the command file: 


Ink30 command file name 


The linker processes input files in the order that it encounters them. If the linker 
recognizes a file as an object file, it links the file. Otherwise, it assumes that 
a file is a command file and begins reading and processing commands from 
it. Note that command filenames are upper/lower-case sensitive, regardless 
of the system used. 


Example 8-1 shows a sample linker command file called link.cmd. 
(Subsection 2.4.2 on page 2-15 contains another example of a linker com- 
mand file.) 


Example 8-1. An Example of a Linker Command File 
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ee ee ee ee a ef 


/* Sample Linker Command File ef 
1 i eR ee ee ee a a ee Af 
a.obj /* First input filename */ 
b.obj /* Second input filename */f 
-O prog.out /* Option to specify output file sat A 
—m prog.map /* Option to specify map file ae 
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Example 8-1 contains only filenames and options. (Note that you can place 
comments in a command file by delimiting them with /* and */.) To invoke the 
linker with this command file, enter: 


ink30 link.cmd 


You can also place other parameters on the command line when you use a 
command file: 


1ink30 -r link.cmd c.obj d.obj 


The linker processes the command file as soon as it encounters it, so a.obj and 
b.obj are linked into the output module before c.obj and d.obj. 


You can also specify multiple command files. If, for example, you have a file 
called names.|st that contains filenames and another file called dir.cmd that 
contains linker directives, you can enter: 


1nk30 names.1lst dir.cmd 


A command file can call another command file; this type of nesting is limited 
to 16 levels. Ifa command file names another command file as input, this state- 
ment must be the /ast statement in the calling command file. 


Blanks and blank lines that appear in a command file are insignificant except 
as delimiters. This also applies to the format of linker directives in a command 
file. Example 8-2 shows a sample command file that contains linker direc- 
tives. (Linker directive formats are discussed in later sections.) 


Example 8-2. A Command File With Linker Directives 


[ROKK KK KK KR A A A I IA AA IA AA A A A IA A A A I I I A / 
rs Sample Linker Command File with Directives * / 
[OK KK KK A A A AA A A AA AA A A A A AA A A A I A I I / 
a.obj b.obj c.obj /* Input filenames */ 
-o prog.out -m prog.map /* Options ial A 
MEMORY /* MEMORY directive ay 
{ 

RAM: o = 100h 1 = 0100h 

ROM: o = 01000h 1 = 0100h 
} 
SECTIONS /* SECTIONS directive S/ 
{ 

-text: > ROM 

-data: > ROM 

-bss: > RAM 
} 
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Note: 


Command Files Are Always Case Sensitive 


Within a command file, all filenames are case sensitive, even on systems 
where case sensitivity does not apply to filenames (DOS, VMS.) |f an input 
file appears more than once in a command file, its case must be the same 


in all instances. 


| 


The following names are reserved as key words for linker directives. Do not 
use them as symbol or section names in a command file. 


align 
attr 
ATTR 
ALIGN 
block 
BLOCK 
COPY 
DSECT 
f 

fill 

FILL 


Reserved Keywords 


GROUP 

| (lowercase “L”) 
len 

length 
LENGTH 
load 
LOAD 
MEMORY 
NOLOAD 
fe) 

org 


origin 
ORIGIN 
page 
PAGE 

run 

RUN 
SECTIONS 
type 

TYPE 
UNION 
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8.5 Object Libraries 


An object library is a partitioned archive file that contains complete object files 
as members. Usually, a group of related modules are grouped together into 
a library. When you specify an object library as linker input, the linker includes 
any members of the library that define existing unresolved symbol references. 
You can use the TMS320C3x/C4x archiver to build and maintain archive 
libraries; Chapter 7 contains more information about the archiver. 


Using object libraries can reduce linking time and can reduce the size of the 
executable module. If a normal object file is specified at link time, it is linked 
whether it is used or not; however, if that same file is placed in an archive 
library, it is included only if it is referenced. 


The order in which libraries are specified is important because the linker 
includes only those members that resolve symbols that are undefined when 
the library is searched. The same library can be specified as often as neces- 
sary; it is searched each time it is included. An alternative is to use the —x 
option, which continually searches all libraries until all references are resolved. 
A library has a table that lists all external symbols defined in the library; the 
linker searches through the table until it determines that it cannot use the 
library to resolve any more references. 


The following example links several object files and libraries; assume the fol- 


lowing: 

_j Input files f1.obj and f2.0bj both reference an external function named 
clrscr. 

_j Input file f1.obj references the symbol origin. 

(J Input file f2.0bj references the symbol filicir. 

1) Library libc.lib, member 0, contains a definition of origin. 

_) Library liba.lib, member 3, contains a definition of fillcir. 

_j Member 1 of both libraries defines cirser. 

If you enter 


1nk30 fl.obj liba.lib f£2.obj libc.lib 


then: 


_) Member 1 of liba.lib satisfies both references to cirscr, because the library 
is searched and cirscr is defined before f2.0bj references it. 

_j Member 0 of libc.lib satisfies the reference to origin. 

_j Member 3 of liba.lib satisfies the reference to fillcir. 
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If, however, you enter: 
1nk30 fl.obj f2.obj libc.lib liba.lib 


then the references to clrscr are satisfied by member 1 of libc.lib. 


If none of the linked files reference symbols defined in a library, you can use 
the —u option to force the linker to include a library member. The next example 
creates an undefined symbol rout? in the linker’s global symbol table: 


1nk30 -u routl libc.lib 


If any members of libc.lib define rout1, then the linker includes those members. 
Note that it is not possible to control the allocation of individual library mem- 
bers; members are allocated according to the SECTIONS directive default al- 
location algorithm. 


Subsection 8.3.9 (page 8-12) describes methods for specifying directories that 
contain object libraries. 
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8.6 The MEMORY Directive 


The linker determines where output sections should be allocated into memory; 
the linker must have a model of target memory to accomplish this task. The 
MEMORY directive allows you to specify a model of target memory, so you can 
define the types of memory your system contains and the address ranges they 
occupy. The linker maintains the model as it allocates output sections, and 
uses the model to determine which memory locations in the target system can 
be used for object code. 


The memory configurations of TMS320 systems differ from application to ap- 
plication. The MEMORY directive allows you to specify a variety of configura- 
tions to meet all applications. After you use the MEMORY directive to define 
amemory model, you can use the SECTIONS directive to allocate output sec- 
tions into defined memory. 


8.6.1 Default Memory Model 


If you do not use the MEMORY directive, the linker uses a default memory 
model that is based on the TMS320C3x/C4x architecture. This model as- 
sumes thatthe full 32-bit address space (232 locations) is presentin the system 
and available for use. 


8.6.2 MEMORY Directive Syntax 


The MEMORY directive identifies ranges of memory that are physically pre- 
sent in the target system and can be used by a program. Each memory range 
has a name, a starting address, and a length. 


When you use the MEMORY directive, be sure to identify all the memory 
ranges that are available to load object code into. Memory that is defined by 
the MEMORY directive is configured memory; any memory that you do not ex- 
plicitly account for with the MEMORY directive is unconfigured memory. The 
linker does not place any part of a program into unconfigured memory. You can 
represent nonexistent memory spaces by simply not including an address 
range in a MEMORY directive statement. 


The MEMORY directive is specified in a command file by the word MEMORY 
(uppercase), followed by a list of memory range specifications enclosed in 
braces. The MEMORY directive in Example 8-3 defines a system that has 4K 
words of ROM at address 0 and 8K of RAM at address OE000h. 
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Example 8-3. The MEMORY Directive 


[1% KK KK KK KK KR A A A A AR A A AR I I I / 


/* Sample command file with MEMORY directive */ 
[8K HK KK KK KR A A A A AR A A A A A A A I I I / 
filel.obj file2.obj /* Input files =f 
-o prog.out /* Options ef 
MEMORY = 
directive eanaate 


{ 
ROM: origin = Q0000h7 , length = 1000h— 


RAM: origin = QOEOOOh7 , length = 2000h— 


origins i lengths— 


Now you could use the SECTIONS directive to tell the linker where to link the 
sections. For example, you could allocate the .text and .data sections into the 
area named ROM and allocate the .bss section into the area named RAM. 


The general syntax for the MEMORY directive is: 


name 1 [(attr)] :origin = constant, length = constant 


name n[(attn] :origin = constant, length = constant 


PAGE identifies a memory space. You can specify up to 255 
pages, depending on your configuration; usually, PAGE 
0 specifies program memory, and PAGE 1 specifies data 
memory. If you do not specify a PAGE, the linker acts as 
if you specified PAGE 0. Each PAGE represents a com- 
pletely independent address space. Configured memory 
on PAGE 0 can overlap configured memory on PAGE 1. 


name Names a memory range. A memory name may be 1 to 
8 characters; valid characters include A—Z, a—z, $, ., and 
_. The names have no special significance to the linker; 
they simply identify memory ranges. Memory range 
names are internal to the linker and are not retained in 
the output file or in the symbol table. Memory ranges on 
separate pages can have the same name; within a page, 
however, all memory ranges must have unique names 
and must not overlap. 


attr 


origin 


length 


fill 
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Specifies one to four attributes associated with the 
named range. Attributes are optional; when used, they 
must be enclosed in parentheses. Attributes can restrict 
the allocation of output sections into certain memory 
ranges. If you do not use any attributes, you can allocate 
any output section into any range with no restrictions. 
Any memory for which no attributes are specified (includ- 
ing all memory in the default model) has all four attrib- 
utes. Valid attributes include: 


R __ specifies that the memory can be read 

W _ specifies that the memory can be written to 

X _ specifies that the memory can contain executable 
code 

I specifies that the memory can be initialized 


If you do not specify any attributes for a memory 
range, then the range has all four attributes. All mem- 
ory in the default model has all four attributes. The fol- 
lowing example defines a memory range that is read- 
able and executable: 


MEMORY 

{ ROM (RX):o0=0,!1=01000h } 

Specifies the starting address of a memory range; enter 
as origin, org, or o. The value, specified in bytes, is a 
16-bit constant and may be decimal, octal, or hexadeci- 
mal. 


Specifies the length of a memory range; enter as length, 
len, or |. The value, specified in bytes, is a 16 bit constant 
and may be decimal, octal, or hexadecimal. 


Specifies a fill character for the memory range; enter as 
fillor f. Fills are optional. The value is a two-byte integer 
constant and may be decimal, octal, or hexadecimal. 
The fill value will be used to fill areas of the memory range 
that are not allocated to a section. 


Linker Description 8-25 


The MEMORY Directive 


Figure 8-2 illustrates the memory map defined by Example 8-3. 


Figure 8-2. Memory Map Defined in Example 8-3 


Memory 
Oh 


1000h 


unconfigured 
OE000h 


10000h 


Unconfigured 


OFFFFFFh 
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8.7 The SECTIONS Directive 


The SECTIONS directive tells the linker how to combine sections from input 
files into sections in the output module and where to place the output sections 
in memory. In summary, the SECTIONS directive: 


_j Describes how input sections are combined into output sections, 
_j Defines output sections in the executable program, 


_} Specifies where output sections are placed in memory (in relation to each 
other and to the entire memory space), and 


_j) Permits renaming of output sections. 


8.7.1 Default Sections Configuration 


If you do not specify a SECTIONS directive, the linker uses a default algorithm 
for combining and allocating the sections. Section 8.11 (page 8-47) describes 
this algorithm in detail. 


8.7.2 SECTIONS Directive Syntax 


eS | 


Note: Compatibility With Previous Versions 


In previous versions of the linker, many of these constructs were specified 
differently. The linker accepts any of the older forms. 


eee ees) 


The SECTIONS directive is specified in a command file by the word 
SECTIONS (uppercase), followed by a list of output section specifications en- 
closed in braces. 


The general syntax for the SECTIONS directive is: 


SECTIONS 
{ 


name : [ property, property, property, ... | 

name : [ property, property, property, ... | 

name : [ property, property, property, ... | 
} 


Each section specification, beginning with name, defines an output section. 
(An output section is a section in the output file.) After the section name is a 
list of properties that define the sections contents and how it is allocated. The 
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properties may be separated by optional commas. Possible properties for a 
section are: 


LOAD ALLOCATION Defines where in memory the section is to be loaded. 


Syntax: load = allocation or 

allocation or 

> allocation 
RUN ALLOCATION defines where in memory the section is to be run. 
Syntax: run = allocation or 


run > allocation 


INPUT SECTIONS defines the input sections comprising the section. 


Syntax: { input_sections } 
SECTION TYPE defines flags for special section types. 
Syntax: type = COPY or 

type = DSECT or 


type = NOLOAD 
For more information on section types, see Section 8.12. 
FILL VALUE defines the value used to fill uninitialized ”holes” 
Syntax: _ fill = va/ue or 
name: ... { ... } = value 
For more information on creating and filling holes, see Section 8.14. 


Example 8-4 shows a SECTIONS directive in a sample linker command file. 
Figure 8—3 shows how these sections are allocated in memory. 


Example 8-4. The SECTIONS Directive 


[OR KK KR AA A A AA A A A I A I Oe I / 
/* Sample command file with SECTIONS directive */ 
[ORK KK IK A I A A A IK I 
filel.obj file2.obj /* Input files */ 
-o prog.out /* Options my 
SECTIONS 
directive ~~) SECTIONS 
{ 
[ -text: load = ROM 
| .const: load = ROM, run = 0809800h 
| .bss: load = RAM, block = 010000h 
| vectors: load = Oh 
section | | { 
specifications tl.obj(.intvecl) 
t2.obj(.intvec2) 
endvec = .; 
L_ } 
.data: align = 32 
} 
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Figure 8-3 shows the five output sections defined by the sections directive in 
Example 8-4; .vectors, .text, .const, .oss, and .data. 


Figure 8-3. Section Allocation Defined by Example 8-4 


The .vectors section is composed of the .intvect1 


00h = ati atO section from t1.obj and the .intvec2 section from 
t2.obj. 


—allocatedin ROM _ The .text section combines the .text sections from 
file1.obj and file2.obj. The linker combines all sec- 
tions named .text into this section. 


—allocatedin ROM The .const section combines the .const sections 
from file1.obj and file2.obj. The application must 
relocate the section to run at O809800h. 


—allocatedin RAM The.bss section combines the .bss sections from 
file1.obj and file2.obj. The .bss section is blocked 
into a space in RAM that is 10000h words long. 


— aligned on 


Se pirOouUnGaly The .data section combines the .data sections from 


file1.obj and file2.obj. The linker will place it any- 
where there is space for it (in RAM in this illustration) 
and align it to a 32-bit boundary. 


8.7.3 Specifying the Address of Output Sections (Allocation) 


The linker assigns each output section two locations in target memory: the lo- 
cation where the section will be loaded and the location where it will be run. 
Usually, these are the same and you can think of each section as having only 
a single address. In any case, the process of locating the output section in the 
target’s memory and assigning its address(es) is called allocation. For more 
information about using separate load and run allocation, see Section 8.8 on 
page 8-35. 


If you do not tell the linker how a section is to be allocated, it uses a default 
algorithm to allocate the section. Generally, the linker puts sections wherever 
they fit into configured memory. You can override this default allocation for a 
section by defining it within a SECTIONS directive and providing instructions 
on how to allocate it. 
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Binding 


You control allocation by specifying one or more allocation parameters. Each 
parameter consists of a keyword, an optional equals sign or greater-than sign, 
and a value optionally enclosed in parentheses. If load and run allocation is 
separate, all parameters following the keyword LOAD apply to load allocation, 
and those following RUN apply to run allocation. Possible allocation parame- 
ters are: 


BINDING allocates a section at a specific address 
-text: load = 0x1000 


MEMORY allocates the section into a range defined in the MEMORY di- 
rective with the specified name or attributes 


.text: load > ROM 


ALIGNMENT - specifies that the section should start on an address bound- 
ary 
-text: align = 0x100 


BLOCKING provides another method of section alignment 
-text: block (0x10000) 


PAGE specifies the memory page to be used (see Section 8.10 on 
page 8-42) 
.text: PAGE 0 


For the load (usually the only) allocation, you may simply use a greater-than 
sign and omit the LOAD keyword: 


.text: > ROM -text: {...} > ROM 
.text: > 0x1000 


If more than one parameter is used, you can string them together as follows: 
-text: > ROM align 16 page 2 
Or if you prefer, use parentheses for readability: 


.text: load = (ROM align(16) page (2)) 


You can supply a specific starting address for an output section by following 
the section name with an address: 


.text: 0x1000 


This example specifies that the .text section must begin at location 1000h. The 
binding address must be a 32-bit constant. 


Output sections can be bound anywhere in configured memory (assuming 
there is enough space), but they cannot overlap. If there is not enough space 
to bind a section to a specified address, the linker issues an error message. 


Memory 


The SECTIONS Directive 


———[—_——  ————— — OO ueaewuwwvwa550 a IS eo 


Note: Binding and Alignment or Named Memory Are Incompatible 


You cannot bind a section to an address if you use alignment or named mem- 
ory. If you try to do this, the linker issues an error message. 


| es) 


You can allocate a section into a memory range that is defined by the 
MEMORY directive. This example names ranges and links sections into them: 


MEMORY 
{ 
ROM (RIX) : origin = Oh, length = 1000h 
RAM (RWIX): origin = 3000h, length = 1000h 
} 
SECTIONS 
{ 
text ; > ROM 
-data ALIGN(64) : > RAM 
.bss : > RAM 


} 


In this example, the linker places .text into the area called ROM. The .data and 
.bss output sections are allocated into RAM. You can align a section within a 
named memory range; the .data section is aligned on a 64-word boundary 
within the RAM range. 


Similarly, you can link a section into an area of memory that has particular 
attributes. To do this, specify a set of attributes (enclosed in parentheses) in- 
stead of amemory name. Using the same MEMORY directive declaration, you 
can specify: 


SECTIONS 

{ 
text: > (X) /* ,text --> executable memory */ 
-data: > (RI) /* .data --> read or init memory */ 
-bss : > (RW) /* .bss  --> read or write memory */ 


} 


In this example, the .text output section can be linked into either the ROM or 
RAM area because both areas have the X attribute. The .data section can also 
go into either ROM or RAM because both areas have the R and | attributes. 
The .bss output section, however, must go into the RAM area because only 
RAM is declared with the W attribute. 


You cannot control where ina named memory range a section is allocated, al- 
though the linker uses lower memory addresses first and avoids fragmentation 
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when possible. In the preceding examples, assuming no other sections had 
been bound to addresses that would interfere with this allocation process, the 
.text section would start at address 0. If a section must start on a specific ad- 
dress, use binding instead of named memory. 


Alignment and Blocking 


You can tell the linker to place an output section at an address that falls on an 
n-word boundary, where n is a power of 2. For example, 


-text: load = align (32) 
allocates .text so that it falls on a cache boundary. 


Blocking is a weaker form of alignment. As with alignment, n must be a power 
of 2. For example, 

bss: load = block(0x10000) 

tells the linker to 


(} Make sure that the output section does not cross a 0x10000 page if it is 
smaller than 0x10000 in length, or 


_j Make sure that it is aligned to start at the beginning of a 0x10000 page if 
it is larger than 0x10000 in length. 


The block keyword does not tell the linker to make sure that the output section 
is not longer than 0x10000. 


You can use alignment or blocking alone or in conjunction with amemory area, 
but alignment and blocking cannot be used together. 


8.7.4 Specifying Input Sections 


An input section specification identifies the sections from input files that are 
combined to form an output section. The linker combines input sections by 
concatenating them in the order in which they are specified. The size of an out- 
put section is the sum of the sizes of the input sections that make up the output 
section. 


Example 8-5 shows the most common type of section specification; note that 
no input sections are listed. 


Example 8-5. The Most Common Method of Specifying Section Contents 


SECTIONS 
{ 
-text: 
-data: 
:bss: 


The SECTIONS Directive 


In Example 8-5, the linker takes all the .text sections from the input files and 
combines them into the .text output section. The linker concatenates the .text 
input sections in the order that it encounters them in the input files. The linker 
performs similar operations with the .data and .bss sections. You can use this 
type of specification for any output section. 


You can explicitly specify the input sections that form an output section. Each 
input section is identified by its filename and section name: 


SECTIONS 
{ 
.text : /* Build .text output section aA 
{ 
fl.obj(.text) /* Link .text section from fl.obj */ 
£2.0bj(secl1) /* Link secl section from f2.o0bj ey 
£3.0b5 /* Link ALL sections from £3.obj ard 


f£4.0bj(.text,sec2) /* Link .text and sec2 from f4.obj */ 


Note that it is not necessary for input sections to have the same name as each 
other or as the output section they become part of. If a file is listed with no sec- 
tions, all of its sections are included in the output section. If any additional input 
sections have the same name as an output section but are not explicitly speci- 
fied by the SECTIONS directive, they are automatically linked in at the end of 
the output section. For example, if the linker found more .text sections in the 
preceding example, and these .text sections were not specified anywhere in 
the SECTIONS directive, then the linker would concatenate these extra sec- 
tions after f4.0b)(sec2). 


The specifications in Example 8—5 are actually a shorthand method for the fol- 
lowing: 


SECTIONS 

{ 
-text: { *(.text) } 
-data: { *(.data) } 
-bss: { *(.bss) } 


} 


The *(.text) means the unallocated .text sections from all the input files. 
This format is useful when: 


LJ You want the output section to contain all input sections that have acertain 
name, but the output section name is different from the input sections’ 
name. 


Lj) You wantthe linker to allocate the input sections before it processes addi- 
tional input sections or commands within the braces. 
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Here’s an example that uses this method: 


SECTIONS 
{ 
-text : { 
abc.obj (xqt) 
*(.text) 
} 
-data : { 
*(.data) 


fil.obj (table) 


} 


In this example, the .text output section contains a named section xqt from file 
abc.obj, which is followed by al/the .text input sections. The .data section con- 
tains al/the .data input sections, followed by a named section table from the 
file fil.obj. Note that this method includes all the unallocated sections. For ex- 
ample, if one of the .text input sections was already included in another output 
section when the linker encountered *(.text), the linker could not include 
that first .text input section in the second output section. 


Specifying a Section’s Runtime Address 


8.8 Specifying a Section’s Runtime Address 


It may be necessary or desirable at times to load code into one area of memory 
and run it in another. For example, you may have performance-critical code 
in a ROM-based system. The code must be loaded into ROM but would run 
much faster if it were in RAM. 


The linker provides a simple way to specify this. In the SECTIONS directive, 
you can optionally direct the linker to allocate a section twice: once to set its 
load address and again to set its run address. For example: 


.fir: load = ROM, run = RAM 


Use the load keyword for the load address and the run keyword for the run ad- 
dress. 


8.8.1 Specifying Two Addresses 


The load address determines where a loader will place the raw data for the 
section. Any references to the section (such as labels in it) refer to its run ad- 
dress. The application must copy the section from its load address to its run 
address; this does not happen automatically just by specifying a separate run 
address. 


If you provide only one allocation (either load or run) for a section, the section 
is allocated only once and will load and run atthe same address. If you provide 
both allocations, the section is actually allocated as if it were two different sec- 
tions of the same size. This means that both allocations occupy space in the 
memory map and cannot overlay each other or other sections. (The UNION 
directive provides a way to overlay sections; see subsection 8.9.1.) 


If either the load or run address has additional parameters, such as alignment 
or blocking, list them after the appropriate Keyword. Everything having to do 
with allocation after the keyword /oad affects the load address until the key- 
word runis seen, after which everything affects the run address. The load and 
run allocations are completely independent, so any qualification of one (such 
as alignment) has no effect on the other. You may also specify run first, then 
load. Use parentheses to improve readability. Examples: 


.data: load = ROM, align = 32, run = RAM 
(align applies only to load ) 

-data: load = (ROM align 32), run = RAM 
(identical to previous example) 


RAM, align 32, 
align 16 


.data: run 
load 


(align 32 in RAM for run, align 16 anywhere for load) 
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8.8.2 Uninitialized Sections 


Uninitialized sections (such as .bss) are not loaded, so the only address of sig- 
nificance is the run address. The linker allocates uninitialized sections only 
once: if you specify both run and load addresses, the linker warns you and ig- 
nores the load address. Otherwise, if you specify only one address, the linker 
treats itas arun address, regardless of whether you call it load or run. Exam- 
ples: 


-bss: load = 0x1000, run = RAM 


A warning is issued, load is ignored, space is allocated in RAM. All of the fol- 
lowing examples have the same effect. The .bss section is allocated in RAM. 


-bss: load = RAM 
-bss: run = RAM 
-bss: > RAM 


8.8.3 Referring to a Load Address by Using the .label Directive 


Any reference to a normal symbol in a section refers to its runtime address. 
However, it may be necessary at runtime to refer to a load-time address. In 
particular, the code that copies a section from its load address to its run ad- 
dress must know where it was loaded. The .label directive in the assembler 
defines a special type of symbol that refers to the load address of the section. 
Thus, whereas normal symbols are relocated with respect to the run address, 
label symbols are relocated with respect to the load address. For more infor- 
mation on the .label directive, see page 4-46. 


TT 
Note: The .asect Directive Is Obsolete 


Allowing separate allocation of run addresses in the linker makes the .asect 
directive obsolete. Any .asect section can be written as a normal section 
(with .sect) and given an absolute run address at link time. However, the 
.asect directive continues to work exactly as before and can still be used. 
Also, the .label directive in an asect works exactly as it did before: it defines 
a relocatable symbol. Now, however, .label can ALSO be used in ANY sec- 


tion to define a (relocatable) symbol that refers to the load address. 
| ee 
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Example 8-6. Copying a Section From ROM to RAM 


sect "fir" 

.label fir _sre ; load address of section 
firs ; run address of section 

<code here> ; code for the section 

.label fir_end ; load address of section end 


text 
src -word fir sre ; src = load address 
dest -word fir ; run address 
LDI @src, ARO ; fetch load address 
LDI @dest,AR1 ; fetch run address 
LDI *ARO++,RO 7 block copy 
RPTS fir_end - fir_sre -1 
LDI *ARO++,RO 


| | STI RO, AR1++ 


7 Jump to section, now on-chip 


CALL fare 7 jump to (runtime) address 


Linker Command File 


[KK KK KK KK RK RAR A RA AAA A A A A AR A I I He / 


/* PARTIAL LINKER COMMAND FILE FOR FIR EXAMPLE */ 
[KK HK KK KK KR RR A A AA A RA A A A A A A A I I I I / 
MEMORY 

ROM: origin = 01000h, length = OFOOOh 

RAM: origin = 0809800h, length = 0400h 
SECTIONS 


-text: load ROM 
hae: load = ROM, run = RAM 


Figure 8-4 illustrates the runtime execution of this example. 
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Figure 8-4. Runtime Execution of Example 8-6 


fir_sre: 
fir_end} 


Application copies 
section at runtime 


fir: 
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8.9 Using UNION and GROUP Statements 


Two SECTIONS statements allow you to conserve memory by GROUPing or 
UNIONing output sections together. Unioning sections causes the linker to al- 
locate the same run address to the sections. Grouping sections causes the 
linker to allocate them contiguously in memory. 


8.9.1 Overlaying Sections With the UNION Directive 


For some applications, you may wish to allocate more than one section to run 
at the same address; for example, you may have several routines you want 
in on-chip RAM at various stages of the program’s execution. Or you may want 
several data objects that you know will not be active at the same time to share 
a block of memory. The UNION statement within the SECTIONS directive pro- 
vides a way to allocate several sections at the same run address. 


Example 8-7. Illustrates the Form of the UNION Statement 


SECTIONS 

{ 
.text: load = ROM 
UNION: run = RAM 


{ 
-bssl: { filel.obj(.bss) } 
-bss2: { file2.obj(.bss) } 
} 
-bss3: run = RAM { globals.obj(.bss) } 


} 


In Example 8-7, the .bss sections from file1.obj and file2.obj are allocated at 
the same address in RAM. The union occupies as much space in the memory 
map as its largest component. The components of a union remain indepen- 
dent sections; they are simply allocated together as a unit. 


Allocation of a section as part of a union affects only its run address. Under 
no circumstances can sections be overlaid for loading. If an initialized 
section is a union member (an initialized section has raw data, such as .text), 
its load allocation must be separately specified. For example: 


Example 8-8. Illustrates Separate Load Addresses for UNION Sections 


UNION run = RAM 
{ 
.text1l: load 
.text2: load 


ROM, { filel.obj(.text) } 
ROM, { file2.obj(.text) } 
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Figure 8-5. Memory Allocation for Example 8-7 and Example 8-8 


Sections cannot 


Illustration of Example 8-7 Illustration of Example 8-8 
) 
load as a union. 
) 


.text 1 (load i 
/ .text 2 (load | 


Zi 


at runtime 


Sections can 
run as a union. 
This is runtime 


allocation only. text 1 (run) 


Wilt 
l, 


Since the .text sections contain data, they cannot /oad as a union, although 
they can be run as a union. Therefore, they each require their own load ad- 
dress. If you fail to provide a load allocation for an initialized section within a 
UNION, the linker issues a warning and allocates load space anywhere it fits 
in configured memory. 


Uninitialized sections do not require load addresses. Uninitialized sections are 
not loaded. 


The UNION statement applies only to allocation of run addresses, so it is re- 
dundant to specify a load address for the union itself. For purposes of alloca- 
tion, the union is treated as an uninitialized section: any one allocation speci- 
fied is considered a run address, and if both are specified, the linker issues a 
warning and ignores the load address. 


ae, | 
Note: Unions and Overlay Pages Are Not the Same 


The UNION capability and the overlay page capability (Section 8.10) may 
sound similar, since they both deal with “overlays”. They are, in fact, quite 
different. UNION allows multiple sections to be overlaid within the same 
memory space. Overlay pages, on the other hand, define multiple memory 
spaces. It is possible to use the page facility to approximate the function of 
UNION, but this is cumbersome. 


sss | 
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8.9.2 Grouping Output Sections Together 


The SECTIONS directive has aGROUP option that forces several output sec- 
tions to be allocated contiguously. For example, assume that a section named 
term_reccontains a termination record for a table in the .data section. You can 
force the linker to allocate .data and term_rec together: 


Example 8-9. Using the GROUP Directive 


SECTIONS 
{ 
.text /* Normal output section * / 
.bss /* Normal output section * / 
GROUP 1000h : /* Specify a group of sections 
«i 
{ 
.data /* First section in the group oy 
term_rec /* Allocated immediately after .data */ 


} 


You can use binding, alignment, or named memory to allocate a GROUP in the 
same manner as a single output section, as shown in Figure 8-6. 


Figure 8-6. Section Allocation Defined by Example 8-9 


The .data section is bound to address 1000h and 
term_rec follows it in memory. 


Note: You Cannot Specify Addresses for Sections Within a GROUP 


When you use the GROUP option, binding, alignment, or allocation into 
named memory can be specified for the group only. You cannot use binding, 


named memory, or alignment for sections within a group. 
|) 
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8.10 Overlay Pages 


Some target systems use an overlay memory configuration in which all or part 
of the memory space is overlaid by shadow memory. This allows the system 
to map different banks of physical memory in and out of a single address range 
in response to hardware selection signals. In this situation, multiple areas of 
physical memory overlay each other at one address. You may want the linker 
to load various output sections into each of these areas or into areas that are 
not mapped at loadtime. 


The linker supports this feature by providing overlay pages. Overlay pages 
allow you to define a memory model that has multiple address spaces. To the 
linker, each possible overlay configuration represents a separate address 
space. Each address range is treated as a separate page and must be confi- 
gured separately with the MEMORY directive. You can then use the 
SECTIONS directive to specify which sections will be mapped into various 
pages. 


8.10.1 Using the MEMORY Directive to Define Overlay Pages 


Each separately configured address space is called a page. To the linker, each 
page represents a completely separate memory that has the full 32-bit range 
of addressable locations. This allows you to link two or more sections at the 
same (or overlapping) addresses if they are on different pages. 


Pages are numbered sequentially, beginning with 0. Page 0 represents the 
normal address space of the TMS320C3x/C4x. The default memory model re- 
sides entirely on page 0. Ifa memory range is specified without a page number, 
the linker assumes it is in page 0. This allows you to ignore the page feature 
for most cases; usually, all sections can be linked in page 0 with no overlays. 


For example, assume that your system can select among three 4K-word long 
banks of physical memory to map into the address space from 1000h to 2000h. 
Although only one bank can be selected at a time, you can initialize each bank 
with different data. Assume you have three output sections called sect0, sect1, 
and sect2 that must be linked into the three banks of memory. This is how you 
would use the MEMORY directive to obtain this configuration: 


Overlay Pages 


Example 8-10. Overlay Pages 


[ORK KK KK I I AA A A AA A I A A I I I / 
/* Example of MEMORY directive with overlay pages */ 
De ee ee a eee Af 
MEMORY 
{ 
PAGE 0: ROM : origin = Oh, length= 1000h 
RAM : origin = 100000h, length= OF0O000 
Oh 
OVR_MEM : origin = 1000h, length= 1000h 
PAGE 1: OVR_MEM : origin = 1000h, length= 1000h 
PAGE 2: OVR_MEM : origin = 1000h, length= 1000h 
} 


This example defines three separate address spaces. Page 0 is the normal 
address space of the TMS320C3x/C4x. It contains the memory ranges ROM 
and RAM; suppose they represent all the memory in the normal address 
space. Page 0 also contains the first bank of overlay memory (OVR_MEM). 
The other two address spaces contain only the additional banks of overlay 
memory, both labeled OVR_MEM. Note that all three OVR_MEM ranges cover 
the same address range. This is possible because each range is on a different 
page and therefore represents a different memory space. 


Figure 87. Overlay Pages Defined by Example 8-10 


PAGE 0 PAGE 1 PAGE 2 
] 
0000h ROM 
OFFFh (.text) 
1000h Overlay 0 Overlay 1 Overlay 2 
{EFEh (sect0) (sect1) (sect2) 


RAM 
(.data, .bss) 


OFFFFFOh 
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8.10.2 Using Overlay Pages With the SECTIONS Directive 


The SECTIONS directive allows you to tell the linker which page an output sec- 
tion should be linked into. Each output section of the program is assigned a 
page as well as an address. You can assign an output section to an overlay 
page by following the section specification with the PAGE option and a page 
number. Assume the use of the MEMORY directive from Example 8—10, the 
SECTIONS definition would be: 


Example 8-11. SECTIONS Directive Definition for Figure 8—7 


n 


ECTIONS 


text: 
.data: 
-bss : 
secto: 
sectl: 
sect2: 


load 
load 
load 
load 
load 
load 


ROM /* Link .text in ROM on page 0 */ 
RAM /* Link .data in RAM on page 0 */ 
RAM /* Link .bss in RAM on page 0 af 
OVR_MEM, page = 0 /* Link sectO into bank 0 ef 
OVR_MEM, page = 1 /* Link sect1l into bank 1 x 
OVR_MEM, page = 2 /* Link sect2 into bank 2 */} 


If you don’t specify a page number for an output section, the linker assumes 
page 0. In this example, .text, .data, and .bss are all linked into the named 
memory areas on page 0. (The PAGE 0 could have been omitted from the 
sect0 definition as well.) 


The PAGE specifications for sectO, sect1, and sect2 tell the linker to link these 
output sections into the corresponding overlay pages. As a result, they all are 
linked to address 1000h, but in different memory spaces. When the program 
is loaded, a loader can configure hardware in such a way that each of these 
sections is loaded into the appropriate bank of memory. 


Within a page, you can bind output sections or use named memory areas in 
the usual way. In the preceding example, notice how sect} is allocated into the 
memory range OVR_MEM. This allows you to define the allocation of sections 
within a page, just as you can in a single memory space. 


Overlay Pages 


For example, the following statement: 
sectl : load = 1200h, page = 1 


links sect at address 1200h in page 1. You can also use page as a “qualifier” 
on the address. For example: 


sectl : load = (1200 PAGE 1) 


If you do not specify any binding or named memory range for the section, the 
linker allocates the section into the page wherever it can (just as it normally 
does with a single memory space). For example, sect2 could also be specified 
as: 


sect2 : PAGE 2 


Because OVR_MEM is the only memory on page 2, it is not necessary (but 
acceptable) to specify = OVR_MEM for the section. 
8.10.3 Page Definition Syntax 


As illustrated in the preceding examples, overlay pages are specified in the 
MEMORY directive by using the following syntax: 


MEMORY 


PAGEO: memory range 
memory range 


memory range 
memory range 


Each page is introduced by the keyword PAGE and a page number, followed 
by acolon and a list of memory ranges the page contains. Memory ranges are 
specified in the normal way. You can define up to 255 overlay pages. Because 
each page represents a completely independent address space, memory 
ranges on different pages can have the same name. Configured memory on 
any page can overlap configured memory on any other page. Within a single 
page, however, all memory ranges must have unique names and must not 
overlap. 
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Any memory ranges listed outside the scope of a PAGE specification default 
to page 0. Consider the following example: 


MEMORY 
{ 
ROM >: org = Oh len = 1000h 
EPROM : org = 1000h len = 1000h 
RAM : org = 2000h len =0OE000h 
PAGE 1: XROM : org = Oh len = 1000h 
XRAM : org = 2000h len =0EO0O0O0h 


} 


The memory ranges ROM, EPROM, and RAM are all on page 0 (because no 
page is specified). XROM and XRAMare on page 1. Note that XROM on page 
1 overlays ROM on page 0, and XRAM on page 1 overlays RAM on page 0. 


In the output link map (obtained with the —m linker option), the listing of the 
memory model is keyed by pages. This provides you with an easy method of 
verifying that you specified the memory model correctly. Also, the listing of out- 
put sections has a PAGE column that identifies the memory space into which 
each section will be loaded. 
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8.11 Default Allocation 


The MEMORY and SECTIONS directives provide flexible methods for build- 
ing, combining, and allocating sections. However, any memory locations or 
sections that you choose not to specify must still be handled by the linker. 
Within the specifications you supply, the linker uses default algorithms to build 
and allocate sections. Subsections 8.11.1 and 8.11.2 describe default alloca- 
tion algorithms. 


8.11.1 Allocation Algorithm 


If you do not use the MEMORY directive the linker assumes that the full 32-bit 
address space is configured and allocates output sections into memory, begin- 
ning at address 0. 


If you do not use the SECTIONS directive, the linker allocates the output sec- 
tions as though the following SECTIONS directive was specified: 


SECTIONS 

{ 
text 
.data 
.bss 


} 


All .text input sections are concatenated to form a .text output section in the 
executable outputfile. All .data input sections are combined to form a .data out- 
put section, and all .bss sections are combined to form a .bss output section. 
Each output section is then allocated into configured memory. 


If the input files contain named sections, the linker links them in after the .bss 
section. Input sections that have the same name are combined into a single 
output section with this name. 


eS | 
Note: Using the SECTIONS Directive Affects Allocation 


When you use the SECTIONS directive, the linker performs no part of the 
default allocation. Allocation is performed according to the rules specified by 


the SECTIONS directive and the rules discussed in subsection 8.11.2. 
| i i ss sss sss 
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8.11.2 General Rules for Output Sections 


An output section can be formed in one of two ways: 
Rule 1 = As the result of a SECTIONS directive definition. 


Rule 2 By combining input sections with the same names into output sec- 
tions that are not defined in a SECTIONS directive. 


If an output section is formed as a result of a SECTIONS directive (rule 1), this 
definition completely determines its contents. (See Section 8.7, page 8-27, for 
examples of how to specify the contents of output sections.) 


An output section can also be formed when input sections are encountered 
that are not specified by any SECTIONS directive (rule 2). In this case, the 
linker combines all such input sections that have the same name into an output 
section with this name. For example, suppose that the files f1.obj and f2.obj 
both contain named sections called Vectors and that the SECTIONS directive 
does not define an output section to contain them. The linker will combine the 
two Vectors sections from the input files into a single output section named 
Vectors, allocate it into memory, and include it in the output file. 


After the linker determines the composition of all the output sections, it must 
allocate them into configured memory. The MEMORY directive specifies 
which portions of memory are configured, or if there is no MEMORY directive, 
the linker uses the default configuration. 


The linker’s allocation algorithm attempts to minimize memory fragmentation. 
This allows memory to be used more efficiently and increases the probability 
that your program will fit into memory. This is the algorithm: 


1) Any output section for which you have listed a specific binding address is 
placed in memory at that address. 


2) Any output section that is included in a specific named memory range or 
that has memory attribute restrictions is allocated. Each output section is 
placed into the first available space within the named area, considering 
alignment where necessary. 


3) Any remaining sections are allocated in the order in which they were de- 
fined. Sections not defined in a SECTIONS directive are allocated in the 
order in which they were encountered. Each output section is placed into 
the first available memory space, considering alignment or blocking where 
necessary. 


Special Section Types (DSECT, COPY, and NOLOAD) 


8.12 Special Section Types (DSECT, COPY, and NOLOAD) 


You can assign three special types to output sections: DSECT, COPY, and 
NOLOAD. These types affect the way that the section is treated when it is 
linked and loaded. You can assign a type to a section by using the type property 
in the section definition. For example: 


SECTIONS 


{ 


} 


DSECT {f1.0b3} 
COPY {£2.ob3} 
NOLOAD {£3.0b3} 


secl: load 
sec2: load 
sec3: load 


200000h, type 
400000h, type 
600000h, type 


LJ The DSECT type creates a dummy section with the following qualities: 


HM Itisnotincluded inthe output section memory allocation. Ittakes up no 
memory and is not included in the memory map listing. 


Mm itcan overlay other output sections, other DSECTs, and unconfigured 
memory. 


m Global symbols defined in a dummy section are relocated normally. 
They appear in the output module’s symbol table with the same value 
they would have if the DSECT had actually been loaded. These sym- 
bols can be referenced by other input sections. 


m Undefined external symbols found in a DSECT cause specified 
archive libraries to be searched. 


m The section’s contents, relocation information, and line number infor- 
mation are not placed in the output module. 


In the preceding example, none of the sections from f1.obj are allocated, 
but all the symbols are relocated as though the sections were linked at ad- 
dress 200000h. The other sections can refer to any of the global symbols 
in sect. 


ACOPY section is similar to a DSECT section, except that its contents and 
associated information are written to the output module. The .cinit section 
that contains initialization tables for the C compiler has this attribute under 
the RAM model. 


ANOLOAD section differs from a normal output section in one respect: the 
section’s contents, relocation information, and line number information 
are not placed in the output module. The linker allocates space for the sec- 
tion, the section is listed in the memory map listing, etc. 
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8.13 Assigning Symbols at Link Time 


Linker assignment statements allow you to define external (global) symbols 
and assign values to them at link time. You can use this feature to assign an 
allocation-dependent value to a variable or a pointer. 


8.13.1 Syntax of Assignment Statements 


The syntax of assignment statements in the linker is similar to that of C assign- 
ment statements: 


symbol = expression; Assigns the value of expression to symbol 
symbol += expression; Adds the value of expression to symbol 
symbol —= expression; Subtracts the value of expression from symbol 
symbol *= expression; Multiplies symbol by expression 

symbol /= expression; Divides symbol by expression 


The symbol should be defined externally in the program. If it is not, the linker 
defines anew symbol and enters it into the symbol table. The expression must 
follow the rules defined in subsection 8.13.3. Assignment statements must be 
terminated with a semicolon. 


The linker processes assignment statements after it allocates all the output 
sections. Thus, if an expression contains a symbol, the address used for that 
symbol reflects the symbol’s address in the executable output file. 


For example, suppose a program reads data from one of two tables identified 
by two external symbols, Table1 and Table2. The program uses the symbol 
cur_tabas the address of the current table; cur_tab must point to either Table1 
or Table2. You could accomplish this in the assembly code, but you would need 
to reassemble the program in order to change tables. Instead, you can use a 
linker assignment statement to assign cur_tab at link time: 


prog.obj /* Input file */ 
cur_tab = Tablel; /* Assign cur_tab to one of the tables */ 


8.13.2 Assigning the SPC to a Symbol 


Aspecial symbol, denoted by a dot (.), represents the current value of the SPC 
during allocation. The linker’s dot (.) symbol is analogous to the assembler’s 
dollar sign ($) symbol. The dot (.) symbol can be used only in assignment 
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statements within a SECTIONS directive, because dot (.) is meaningful only 
during allocation, and the SECTIONS directive controls the allocation process. 


For example, suppose a program needs to know the address of the beginning 
of the .data section. You can create an external undefined variable called 
Dstart in the program by using the .global directive. Then, assign the value of 
“.’ to Dstart: 


SECTIONS 
{ 


text: 
.data: { Dstart = .; } /* Dstart = current SPC value */ 
-bss 3: 


} 


This defines Dstart to be the ultimate linked address of the .data section. The 
linker will relocate all references to Dstart. If the section has separate load and 


run addresses, “.” refers to the run address. 


ony 


A special type of assignment assigns a value to the “.” symbol. This adjusts 
the location counter within an output section and creates a hole between two 


ony 


input sections. Any value assigned to “.” to create a hole is relative to the begin- 


ning of the section, not to the address actually represented by “.”. Assignments 


to “.” and holes are described in Section 8.14. 


8.13.3 Assignment Expressions 
These rules apply to linker expressions: 


_) Expressions can contain global symbols, constants, and the C language 
operators listed in Table 8—2. 


_j All numbers are treated as long (32-bit) integers. 


(4 Constants are identified in the same manner as they are by the assembler. 
Thatis, numbers are recognized as decimals unless they have a suffix (H 
or h for hexadecimal and Q or q for octal). C language prefixes are also 
recognized (0 for octal and Ox for hex). Hexadecimal constants must begin 
with a digit. No binary constants are allowed. 


_j Symbols within an expression have only the value of the symbol’s 
address. No type checking is performed. 


(4 Linker expressions can be absolute or relocatable. If an expression con- 
tains any relocatable symbols (and zero or more constants or absolute 
symbols), itis relocatable. Otherwise, the expression is absolute. If asym- 
bol is assigned the value of a relocatable expression, the symbol is 
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relocatable; if assigned the value of an absolute expression, the symbol 
is absolute. 


The linker supports the C language operators listed in Table 8—2 in order of 
precedence. Operators in the same group have the same precedence. 


Besides the operators listed in Table 8-2, the linker also has an align operator 
that allows a symbol to be aligned on an n-word boundary within an output sec- 
tion (nis a power of 2). For example, the expression: 


. = align(16); 


aligns the SPC within the current section on the next 16-word boundary. Be- 
cause the align operator is a function of the current SPC, it can be used only 
in the same context as “.” — that is, within a SECTIONS directive. 


Table 8-2. Operators in Assignment Expressions 


Group 1 (Highest Precedence) | Group 6 
| Logical not & Bitwise AND 
oe Bitwise not 
7 Negative 
Group 2 | Group 7 
i Multiplication | Bitwise OR 
/ Division 
% Mod 
Group 3 | Group 8 
+ Addition && Logical AND 
- Minus 
Group 4 | Group 9 
>> Arithmetic right shift || Logical OR 
<< Arithmetic left shift 
Group 5 | Group 10 (Lowest Precedence) 
== Equal to = Assignment 
l= Not equal to += A+=B > A=A+B 
> Greater than -= A-=B > A=A-B 
< Less than = A*=B +> A=A*B 
<= Less than or equal to /= A/=B —> A=A/B 
>= Greater than or equal to 
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8.13.4 Symbols Defined by the Linker 


The linker automatically defines six symbols that a program can use at runtime 
to determine where a section is linked. These symbols are external, so they 
appear inthe link map. They can be accessed in any assembly language mod- 
ule if they are declared with a .global directive. 


Values are assigned to these symbols as follows: 


.text is assigned the first address following the .text output section. (It 
marks the beginning of executable code.) 


etext is assigned the first address following the .text output section. (lt 
marks the end of executable code.) 


.data is assigned the first address following the .data output section. (It 
marks the beginning of initialized data tables.) 


edata is assigned the first address following the .data output section. (lt 
marks the end of initialized data tables.) 


-bss __ is assigned the first address of the .bss output section. (It marks the 
beginning of uninitialized data.) 


end is assigned the first address following the .bss output section. (It 
marks the end of uninitialized data.) 


Symbols Defined Only for C Support (—c or —cr option) 


cinit is assigned the first address of the .cinit section (-| for 
—Cr). 


__STACK_SIZE __ is assigned the size of the .stack section. 
__SYSMEM_SIZE _is assigned the size of the .sysmem section. 
_SYSMEM8 SIZE _ is assigned the size of the .sysm8 section (’C32 only). 
_SYSMEM16_SIZE is assigned the size of the .sysm16 section (’C32 only). 
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8.14 Creating and Filling Holes 


The linker provides you with the ability to create areas within output sections 
that have nothing linked into them. These areas are called holes. In special 
cases, uninitialized sections can also be treated as holes. This section de- 
scribes how the linker handles such holes and how you can fill holes (and 
uninitialized sections) with a value. 


8.14.1 Initialized and Uninitialized Sections 


There are two rules to remember about the contents of an output section. An 
output section contains either: 


_j An output section contains raw data for the entire section, or 


_j An output section contains no raw data. 


A section that has raw data is referred to as initialized. This means that the 
object file contains the actual memory image contents of the section. When the 
section is loaded, this image is loaded into memory at the section’s specified 
starting address. The .text and .data sections always have raw data if anything 
was assembled into them. Named sections defined with the .sect or .asect as- 
sembler directives also have raw data. 


By default, the .bss section and .usect sections have no raw data (they are 
uninitialized). They occupy space in the memory map but have no actual con- 
tents. Uninitialized sections typically reserve space in RAM for variables. In the 
object file, an uninitialized section has a normal section header and may have 
symbols defined in it; however, no memory image is stored in the section. 


8.14.2 Creating Holes 


You can create a hole in an initialized output section. A hole is created when 
you force the linker to leave extra space between input sections when building 
an output section. When such a hole is created, the linker must follow the first 
guideline and supply raw data for the hole. 


Holes can be created only within output sections. There can also be space be- 
tween output sections, but such spaces are not holes. There is no way to fill 
or initialize the space between output sections. 


To create a hole in an output section, you must use a special type of linker as- 
signment statement within an output section definition. The assignment state- 
ment modifies the SPC (denoted by “.”) by adding to it, assigning a greater 
value to it, or aligning it on an address boundary. The operators, expressions, 
and syntax of assignment statements are described in Section 8.13 (page 
8-50). 
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The following example shows how holes can be created in output sections 
using assignment statements: 


SECTIONS 
{ 


Sutsect : 


{ 
filel.obj(.text) 


. += 100h; /* Create a hole with size 100h */ 
file2.obj(.text) 

- = align(16); /* Create a hole to align the SPC ad 
file3.obj 


} 
The output section outsect is built as follows: 


The .text section from file1.obj is linked in. 

The linker creates a 256-word hole. 

The .text section from file2.obj is linked in after the hole. 

The linker creates another hole by aligning the SPC on a 16-word bound- 
ary. 

Finally, the .text section from file3.obj is linked in. 


UO OOOO 


oo 


All values assigned to the “.” symbol within a section refer to the relative 
address within the section. The linker handles assignments to the “.” symbol 
as if the section started at address 0 (even if you specify a binding address). 
Consider the statement . = align(16) in the preceding example. This statement 
effectively aligns file3.obj .text to start on a 16-word boundary within outsect. 
If outsect is ultimately allocated to start on an address that is not aligned, then 


file3.text will not be aligned either. 


Expressions that decrement “.” are illegal. For example, it is invalid to use the 
—= operator in an assignment to “.”. The most common operators used in 
assignments to “.” are += and align. 

If an output section contains all input sections of a certain type (such as .text), 
you can use the following statements to create a hole at the beginning or end 
of the output section: 


.text: { .+= 100h; } /* Hole at the beginning */ 
.data: { 

*(.data) 

. t= 100h; } /* Hole at the end */ 
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8.14.3 Filling Holes 


Another way to create a hole in an output section is to combine an uninitialized 
section with initialized sections to form a single output section. /n this case, the 
linker treats the uninitialized section as a hole and supplies data for it. An ex- 
ample of creating a hole in this way is: 


SECTIONS 


{ 


} 


outsect: 
{ 
filel.obj(.text) 
filel.obj(.bss) /* This becomes a hole */ 


Because the .text section has raw data, all of outsect must also contain raw 
data (first guideline). Therefore, the uninitialized .bss section becomes a hole. 


Note that uninitialized sections become holes only when they are combined 
with initialized sections. If multiple uninitialized sections are linked together, 
the resulting output section is also uninitialized. 


Whenever there is a hole in an initialized output section, the linker must supply 
raw data to fill it. The linker fills holes with a 4-byte fill value that is replicated 
through memory until it fills the hole. The linker determines the fill value as fol- 
lows: 


1) 


Ifthe hole is formed by combining an uninitialized section with an initialized 
section, you can specify a fill value for that specific initialized section. Fol- 
low the section name with an = symbol and a 4-byte constant: 


SECTIONS 
{ 


outsect: 
{ 
filel.obj(.text) 
file2.obj(.bss) = OFFh /* Fill this hole */ 
} /* with QOOOOOOFFh */ 
} 


You can also specify a fill value for all the holes in an output section by us- 
ing the fill Keyword. For example, 


SECTIONS 


{ 
outsect:f£111 = OFFOOh /* fills holes with OFFOOh */ 


{ 


. += 10h; /* This creates a hole */ 
filel.obj(.text) 
filel.obj(.bss) /* This creates another hole*/ 
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3) If you do not specify an initialization value for a hole, the linker fills the hole 
with the value specified with -f. For example, suppose the command file 
link.cmd contains the following SECTIONS directive: 


SECTIONS 


{ 
.text: { .= 100; } /* Create a 100-word hole*/ 


} 

Now invoke the linker with the —f option: 
1nk30 -f£ OFFFFFFFFh link.cmd 
This fills the hole with OFFFFFFFFh. 


4) If you do not invoke the linker with —f, the linker fills holes with Os. 


Whenever a hole is created and filled in an initialized output section, the hole 
is identified in the link map along with the value the linker uses to fill it. 


8.14.4 Explicit Initialization of Uninitialized Sections 


An uninitialized section becomes a hole only when itis combined with an initial- 
ized section. When uninitialized sections are combined with each other, the 
resulting output section remains uninitialized and has no raw data in the output 
file. 


However, you can force the linker to initialize an uninitialized section simply by 
specifying an explicit fill value for it in the SECTIONS directive. This causes 
the entire section to have raw data (the fill value). For example, 


SECTIONS 
{ 


-bss: £111 = 11223344h /* Fills .bss with 11223344h */ 
} 


cage 
Note: Filling Sections 


Because filling a section (even with Os) causes raw data to be generated for 
the entire section in the output file, your output file will be very large if you 


specify fill values for large sections or holes. 
|e | 
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8.15 Partial (Incremental) Linking 


An output file that has been linked can be linked again with additional modules. 
This is known as partial linking or incremental linking. Partial linking allows 
you to partition large applications, link each part separately, and then link all 
the parts together to create the final executable program. 


Follow these guidelines for producing a file that you will relink: 


a 


a 


Intermediate files must have relocation information. Use the -r option 
when you link the file the first time. 


Intermediate files must have symbolic information. By default, the linker 
retains symbolic information in its output. Do not use the —s option if you 
plan to relink a file, because —s strips symbolic information from the output 
module. 


Intermediate link steps should be concerned only with the formation of out- 
put sections and not with allocation. All allocation, binding, and MEMORY 
directives should be performed in the final link. 


If the intermediate files have global symbols that have the same name as 
global symbols in other files and you wish them to be treated as static (vis- 
ible only within the intermediate file), you must link the files with the —h op- 
tion (See subsection 8.3.6 on page 8-10.) 


If you are linking C code, don’t use —c or —cr until the final link step. Every 
time you invoke the linker with the —c or —cr option the linker will attempt 
to create an entry point. 


The following example shows how you can use partial linking: 


Step 1: Link the file file1.com; use the -r option to retain relocation informa- 


tion in the output file tempoutt1.out. 
1ink30 -r -o tempoutl filel.com 


file1 .com contains: 


SECTIONS 
{ 
ssl: { 
fl.obj 
£2.0bj 
fn.obj 
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Step 2: Link the file file2.com; use the -r option to retain relocation informa- 
tion in the output file tempout2. out. 


1nk30 -r -o tempout2 file2.com 
file2.com contains: 


SECTIONS 
{ 
ss2: { 
gl.obj 
g2.0bj 
gn.obj 


} 
Step 3: Link tempout1.out and tempout2.out. 


1ink30 -m final.map -o final.out tempoutl.out tempout2.out 
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8.16 Linking C Code 


The TMS320C3x/C4x C compiler produces assembly language source code 
that can be assembled and linked. For example, a C program consisting of 
modules prog1, prog2, etc., can be assembled and then linked to produce an 
executable file called prog.out. 


1nk30 -c -o prog.out progl.obj prog2.obj ... rts.lib 


The —c option tells the linker to use special conventions that are defined by the 
C environment. The archive library rts.lib contains C runtime support func- 
tions. 


For more information about C, including the runtime environment and runtime 
support functions, see the TMS320C3x/C4x Optimizing C Compiler User’s 
Guide. 


8.16.1 Runtime Initialization 


All C programs must be linked with an object module called boot.obj, which 
contains code and data for initializing the runtime environment. 


When a program begins running, this code is executed first and performs the 
following actions: 

_j Sets up the system stack 

_j Processes the runtime initialization table and autoinitializes global vari- 
ables (in the ROM model). 

[j Disables interrupts and calls _main 


The runtime support source library, rts.src, contains boot.obj. You can: 

(j Use the archiver to extract boot.obj from the library and then link it in di- 
rectly, or 

(1 Include a library created from rts.src (Such as rts30.lib or rts40.lib) as an 
input file, and the linker will extract boot.obj when you use the —c or —cr 
option. 


8.16.2 Object Libraries and Runtime Support 


The TMS320C3x/C4x Optimizing C Compiler User’s Guide describes addi- 
tional runtime support functions that are included in rts.src. If your program 
uses any of these functions, you must link a library created from rts.src with 
your object files. 


You can also create your own object libraries and link them. The linker will in- 
clude and link only those modules in a library that resolve undefined 
references. 
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8.16.3 Setting the Size of the Stack and Heap Sections 


For 32-bit memory widths, C uses the uninitialized section called .sysmem 
for the memory pool used by malloc(). 


For the ’C32’s 8-bit and 16-bit memory widths, the uninitialized sections 
.sysm8 and .sysm16 are used for the memory pool used by malloc8() and 
malloc16(), respectively. 


In any memory width, the uninitialized section called .stack is used for the 
memory pool used by the runtime stack. 


You can set the size of these sections by using the -heap, —heap8, —heap16, 
or —stack option and specifying the size of the section as a four byte constant 
immediately after the option. The default size for the .stack and .heap sections 
is 1K words. 


The .sysm8 and .sysm16 sections are not created unless the 8—bit or 16-bit 
memory allocation functions are used in the executable. In this case, the 
sections default to 1K 8—bit words or 1K 16-bit words, respectively. Specifying 
the —heap8 or —heap16 option when the memory functions are not used has 
no effect. 


If the -w option has been specified, a warning will be issued when one of these 
sections is created with its default size. 


8.16.4 Autoinitialization (ROM and RAM Models) 


The C compiler produces tables of data that are used to autoinitialize global 
variables. These are contained in a special section called .cinit. The initializa- 
tion tables can be used for autoinitialization in either of two ways. 


(J RAM Model (-cr option) 


Variables are initialized at loadtime. This can enhance performance by re- 
ducing boot time and can save memory used by the initialization tables. 
(Note that you must use a smart loader to take advantage of the RAM 
model of autoinitialization.) 


When you use —cr, the linker marks the .cinit section with a special attrib- 
ute. This attribute tells the linker not to load the .cinit section into memory. 
The linker also sets the cinit symbol to —1; this informs the C boot routine 
that initialization tables are not present in memory. Thus, no runtime in- 
itialization is performed at boot time. 


When the program is loaded, the loader must be able to: 


m Detect the presence of the .cinit section in the object file. 
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m Detect the presence of the attribute that tells it not to copy the .cinit 
section. 


m Understand the format of the initialization tables (this is described in 
the TMS320C3x/C4x Optimizing C Compiler User’s Guide). 


The loader then uses the initialization tables directly from the object file to 
initialize variables in .bss. 


Figure 8-8 illustrates the RAM autoinitialization model. 


Figure 8-8. RAM Model of Autoinitialization 


Object File Memory 


loader 


(J) ROM Model (-c option) 


Variables are initialized at runtime. The .cinit section is loaded into mem- 
ory along with all the other sections. The linker defines a special symbol 
called cinit that points to the beginning of the tables in memory. When the 
program begins running, the C boot routine copies data from the tables 
into the specified variables in the .bss section. This allows initialization 
data to be stored in ROM and then copied to RAM each time the program is 
started. 


Figure 8-9 illustrates the ROM autoinitialization model. 
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Figure 8-9. ROM Model of Autoinitialization 
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8.16.5 The -c and -cr Linker Options 


The following list outlines what happens when you invoke the linker with the 
—c or —cr option. 


| 


Lj 


| 


The symbol _c_int00 is defined as the program entry point. _c_intO0 is the 
start of the C boot routine in boot.obj; referencing _c_intOO ensures that 
boot.obj will automatically be linked in from the runtime support library. 


The .cinit output section is padded with a termination record so that the 
boot routine (ROM model) or the loader (RAM model) knows when to stop 
reading the initialization tables. 


In the ROM model (-c option), the linker defines the symbol cinit as the 
starting address of the .cinit section. The C boot routine uses this symbol 
as the starting point for autoinitialization. 


In the RAM model (—cr option): 


mM The linker sets the symbol cinit to —1. This indicates that the initializa- 
tion tables are not in memory, so no initialization is performed at boot 
time. 


mM The STYP_COPY flag (010h) is set in the .cinit section header. 
STYP_COPY is the special attribute that tells the loader to perform 
autoinitialization directly and not to load the .cinit section into memory. 
The linker does not allocate space in memory for the .cinit section. 
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8.17 Linker Example 
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This example links three object files named demo.obj, fft.obj, and tables.obj 
and creates a program called demo.out. The symbol SETUP is the program 
entry point. 


Assume that target memory has the following configuration: 


Address Range: Contents: 
000000h to OOOFFFh 4K on-chip ROM 
809800h to 809BFFh Internal RAM block BO 


809C00h to 809FFFh Internal RAM block B1 
80A000h to 10087FFh External RAM 


The output sections are constructed from the following input sections: 


(1 A set of interrupt vectors from section int_vecs in the file tables.obj must 
be linked at address 0 in ROM. 


(} Executable code, contained in the .text sections of demo.obj and fft.obj, 
must also be linked into ROM. 


1 Two tables of coefficients, which are in the .data sections of the files 
tables.obj and fft.obj, must be linked into RAM block BO. The remainder 
of block BO must be initialized to the value OFFCC1122h. 


Lj) The .bss section from fft.obj, which contains variables, must be linked into 
block B1 of data RAM. The unused part of this RAM must be initialized to 
OFFFFFFFFh. 


(1 The .bss section from demo.obj, which contains buffers and variables, 
must be linked into external RAM. 


Figure 8-10 shows the linker command file for this example; Figure 8-11 
shows the map file. 
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Figure 8-10. Linker Command File, demo.cmd 


[ROR KKK KKK KK KKK IKK KK KR IKK KR IRR RR IKI RAR IK IRI I OR / 


[Reee Specify Linker Options BREE f 
[RR KKK KKK KK KKK IKK KKK IRI RRR IA IR IRR IR IIA I I I / 


-e SETUP /* Define the entry point dt 
-o demo.out /* Name the output file */ 
—-m demo.map /* Create a load map xf 


[RRR KK KKK KK KKK IK KR IR IRI RAR IRA IR IR AR IR II I I I I / 


[RRR Specify the Input Files tilly 


[RR KKK KKK KK KKK IKK KK RR IR KR IR IRA RAR IK AR IR II A I / 


demo.obj 
fft.obj 
tables.obj 


[RR KK RI KK KR KR IKK IK ARR IR AR RR IRA RRR IRR IR IRA II IO I / 


[EERE Specify the Memory Configuration wee / 
[ROR KKK KK KK KK KK IKK IK KK IK RR IR IRA RRR IRR IR AKA I A I / 


MEMORY 
{ 
ROM: origin = 0000000h length = 01000h 
RAM_BO: origin = 0809800h length = 0400h 
RAM_B1: origin = 0809C00h length = 0400h 
RAM origin = 080A000h length = 07FE800h 
} 
[RRR KR IKK IK RRR IRA RRR IR RR RR IR AR RR IKARIA IRA IK IO I / 
Lor Specify the Output Section italy f 


[RR KK KK KK IK KKK IRR KARR IR AIR RRR IR AR IR IRA RAR IRA IRI I / 


SECTIONS 
{ 
text: load = ROM /* Link all .text sections into ROM */ 
int_vecs: load = Oh /* Link interrupts at 0 */ 
.data: load = RAM_BO /* Link the .data sections into BO */ 
tables.obj(.data) /* .data input section * if 
fft.obj(.data) /* .data input section */] 
= 400h; /* Create a hole to end of block */ 
, £111 = OFFCC1122h /* and fill with OFFCC1122h a]: 
fftvars: load = RAM Bl /* Create a new fftvars section * 
fft.obj(.bss) 
, £111 = OFFFFFFFFh /* link into Bl and fill w/OFFFFFFFFh */ 
-bss: load = RAM /* Link all remaining .bss sections */ 
} 
[RR KK RI KK IKK RRR IKK IR ARR IR RR RR IRA RRR IKARIA IRA IK IO I / 
[KKK End of Command File ERR / 


[RK KK RAK RIK ARR IRA IR ARIK AR RAIA IR IKARIA IRA IA IO I / 


Invoke the linker with the following command: 


1nk30 demo.cmd 


This creates the map file shown in Figure 8—11 and an output file called 
demo.out that can be run on the TMS320C8x. 
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Figure 8—11.Output Map File, demo.map 


KKK KKK KKK KKK KKK KKK KKK KK KKK KK KKK KKKKKKKKKKKKK KKK KKK KKK 
TMS320C3x/4x COFF Linker Version x.xx 
KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKK KKK KKK KKK 
OUTPUT FILE NAME: <demo.out> 
ENTRY POINT SYMBOL: “SETUP” address: 00000028 
EMORY CONFIGURATION 
name origin length attributes £211 
ROM 00000000 000001000 RWIX 
RAM_BO 00809800 000000400 RWIX 
RAM_B1 00809c00 000000400 RWIX 
RAM 0080a000 0007fe800 RWIX 
SECTION ALLOCATION MAP 
output attributes/ 
section page origin length input sections 
text 0 00000000 00000000 UNINITIALIZED 
int_vecs 0 00000000 00000028 
00000000 00000028 tables.obj (int_vecs) 
.data 0 00809800 00000400 
00809800 00000064 tables.obj (.data) 
00809864 00000014 fft.obj (.data) 
00809878 00000388 —-HOLE-- [fill = ffccl1122] 
fftvars 0 00809c00 00000080 
00809c00 00000080 fft.obj (.bss) [fill = ffffffff] 
.bss 0 0080a000 00000020 UNINITIALIZED 
0080a000 00000020 demo.obj (.bss) 
-text 0 00000028 OOO0O000fE 
00000028 000000ee demo.obj (.text) 
00000116 00000011 fft.obj (.text) 
GLOBAL SYMBOLS 
address name address name 
0080a000 .bss 00000028 .text 
00809800 .data 00000028 SETUP 
00000028 .text 00000047 main 
00000028 SETUP 000000ec sub 
00809864 coeff 00000116 fft 
00809c00 data_in 00000127 etext 
00809c00 edata 00809800 tables 
0080a020 end 00809800 .data 
00000127 etext 00809864 coeff 
00000116 fft 00809c00 edata 
00000047 main 00809c00 data_in 
000000ec sub 0080a000 vars 
00809800 tables 0080a000 .bss 
0080a000 vars 0080a020 end 
{14 symbols] 
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Absolute Lister Description 


The absolute lister is a debugging tool that accepts linked object files as input 
and creates .abs files as output. These .abs files can be assembled to produce 
alisting that shows the absolute addresses of object code. Manually, this could 
be a tedious process requiring many operations; however, the absolute lister 
utility performs these operations automatically. 
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9.1 Producing an Absolute Listing 


Figure 9-1 illustrates the steps required to produce an absolute listing. 


Figure 9—1. Absolute Lister Development Flow 


Assembler First, assemble a source file. 
source file 


Link the resulting object file. 


Invoke the absolute lister; use the linked object 
file as input. This creates a file with an .abs 
extension. 


Finally, assemble the .abs file; you must 


invoke the assembler with the —a option. This 
produces a listing file that contains absolute 


TT addresses. 
Absolute 
listing 
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9.2 Invoking the Absolute Lister 


The syntax for invoking the absolute lister is: 


abs30 [-options] input file 


abs30 is the command that invokes the absolute lister. 


options identifies the absolute lister options that you want to use. 
Options are not case sensitive and can appear anywhere on the 
command line following the command. Precede each option 
with a hyphen (—). The absolute lister options are as follows: 


-¢ enables you to change the default naming conventions 
for filename extensions on assembly files, C source files, 
and C header files. The three options are listed below. 


Lj -ea[.Jasmext for assembly files (default is .asm) 
_j -ec [.]cext for C source files (default is .c) 
Lj -eh [.]hext for C header files (default is .h) 


The “.” in the extensions and the space between the 
option and the extension are optional. 


-q (quiet) suppresses the banner and all progress infor- 
mation. 


input file names the linked object file. If you do not supply an extension, 
the absolute lister assumes that the input file has the default 
extension .out. If you do not supply an input filename when you 
invoke the absolute lister, the absolute lister will prompt you for 
one. 


The absolute lister produces an output file for each file that was linked. These 
files are named with the input filenames and an extension of .abs. Header files, 
however, do not generate a corresponding .abs file. 


Assemble these files with the —-a assembler option as follows to create the 
absolute listing: 


asm30 -a filename.abs 


The -e options affect both the interpretation of filenames on the command line 
and the names of the output files. They should always precede any filename 
on the command line. 
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The —e options are particularly useful when: 


(j the linked object file is created from C files compiled with the debugging 
option (-g compiler option) and 


(4 the source files do not use the standard extensions (.c for C source files, 
.h for header files, and .asm for assembly files). 


The absolute lister uses file extensions to determine how to treat the source 
files listed in the linked object file. 


For example, suppose the C source file hello.csr is compiled with debugging 
set; this generates the assembly file hello.s. hello.csr also includes hello.hsr. 
Assuming the executable file created is called hello.out, the following 
command will generate the proper .abs file: 


abs30 -ea s -ec csr -eh hsr hello.out 


With the -e options appropriately specified in this example, the absolute lister 
will: 


[} recognize hello.hsr as a header file and therefore not create an .abs file 
for it 


(J create hello.abs for the hello.csr file 


Lj use the .copy directive within the hello.abs file to include assembly file 
hello.s, rather than hello.asm 


Note that you need to use the -k compiler option when compiling the original 
source file so that you retain the assembly files for inclusion when you re- 
assemble the .abs files. 
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9.3 Absolute Lister Example 


This example uses three source files. module1.asm and module2.asm both 
include the file globals.def. 


module1.asm 


- text 

.bss array,100 
-bss dflag, 2 
-copy globals.def 


ldp offset, DP 
ldi @offset, R1 
ldp dflag, DP 

ldi @dflag, R1 


module2.asm 


-bss offset, 2 
-copy globals.def 


ldp offset, DP 

ldi @offset, R1 

ldp array, DP 

ldi @array, Rl 
globals.def 


-global dflag 
-global array 
-global offset 


The following steps create absolute listings for the files module1.asm and 
module2.asm: 


Step 1: First, assemble module1.asm and module2.asm: 


asm30 modulel 
asm30 module2 


This creates two object files called module1.obj and module2.obj. 
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Step 2: Next, link module1.obj and module2.obj. using the following linker 
command file, called bttest.cmd: 


[KK KK RK A A A A A AA AA A I I He I 


/* File bttest.cmd -- COFF linker command file */ 
/* for linking TMS320C3x modules */ 


[ORK KK KK KI I I A A I TK KK KK / 


-o bttest.out /* Name the output file */ 
-m bttest.map /* Create an output map */ 


[RK KK KK RR I A A AA AA A I He I 


[* Specify the Input Files aA 


[BORK KK KK KI KK I A A AA A A I I / 


modulel.obj 
module2.obj 


[ROR KK KK KK I A A AA A I I / 


/* Specify the Memory Configurations */ 
[ORK KK A A RA A A A AA A I I I He I / 
MEMORY 


{ 
RAMO: org=0x809800 len=0x400 /* RAM BLOCK 0*/ 
RAM1: org=0x809c00 len=0x400 /* RAM BLOCK 1*/ 
} 


[RK KK KK A A A A A AA A I I He I / 


[* Specify the Output Sections as 
[RR KK KK KK KR I A I AA A A A I I I I / 
SECTIONS 
{ 
-data: > RAMO /* Initialize Data xf 
.text: > RAMO /* Variables Ry 
.bss: > RAMI /* Code */ 


Invoke the linker: 
1nk30 bttest.cmd 


This creates an executable object file called bttest.out; use this new 
file as input for the absolute lister. 
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Now, invoke the absolute lister: 
abs30 bttest.out 
This creates two files called module1.abs and module2.abs: 


modulet.abs: 


-nolist 

array .setsym 000809800h 

dflag .setsym 000809864h 

offset .setsym 000809866h 

.data .setsym 000809800h 

edata .setsym 000809800h 

-bss .setsym 000809800h 

end .setsym 000809868h 

-text .setsym 0008098c00h 

etext .setsym 0008098c08h 
.setsect " .text”,0008098c00h 
-setsect ”,data”,000809800h 
-setsect ” .boss”,000809800h 
-list 
text 
. copy "“modulel.asm” 


module2.abs: 


-nolist 

array .setsym 000809800h 

dflag .setsym 000809864h 

offset .setsym 000809866h 

-data .setsym 000809800h 

edata .setsym 000809800h 

-bss .setsym 000809800h 

end .setsym 000809868h 

-text .setsym 0008098c00h 

etext .setsym 0008098c08h 
-setsect " .text”,0008098c04h 
-setsect ",data”,000809800h 
-setsect ”.boss”,000809866h 
-list 
text 
. copy "“module2.asm” 
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These files contain the following information that the assembler 
needs when you invoke it in step 4: 


L) They contain .setsym directives, which equate values to global 
symbols. Both files contain global equates for the symbol dflag. 
The symbol dflag was defined in the file globals.def, which was 
included in module1.asm and module2.asm. 


J They contain .setsect directives, which define the absolute 
addresses for sections. 


_j) They contain .copy directives, which tell the assembler which 
assembly language source file to include. 


The .setsym and .setsect directives are not useful in normal assem- 
bly; they are useful only for creating absolute listings. 


Step 4: Finally, assemble the .abs files created by the absolute lister 
(remember that you must use the —a option when you invoke the 
assembler): 
asm30 -a modulel.abs 
asm30 -a module2.abs 
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This creates two listing files called module1.lst and module2.Ist; no 
object code is produced. These listing files are similar to normal list- 
ing files; however, the addresses shown are absolute addresses. 


The absolute listing files created are module1.Ist (see Figure 9-2) 


a 


Figure 9-2. module1.!/st 


nd module2.Ist (see Figure 9-3). 


TMS320C3x/C4x COFF Assembler 
Copyright (c) 1987-1997 


modulel.abs 


00809c00 


1 00809c00 
00809800 
00809864 


00809c00 08700080! 
00809c01 08219866! 
00809c02 08700080- 
00809c03 08219864- 


PPrrrunwwnwPYPPp pp 
DMIKDRUOBRWNHEBWD 


Zz 


o Errors, No Warnings 


Version xX.xx Wed Oct 16 12:00:05 1997 
Texas Instruments Incorporated 


PAGE 


«text 
. COpy 
-text 
-bss array, 100 
-bss dflag, 2 
-copy globals.def 
-global dflag 
-global array 
-global offset 


"modulel.asm” 


ldp offset, DP 
ldi @offset, R1 
ldp dflag, DP 
ldi @dflag, Rl 


1 
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Figure 9-3. module2.|st 


module2.abs 


15 00809c04 
16 


pa 


00809866 


00809c04 
00809c05 
00809c06 
00809c07 


PrPPrrwWewWwWwW PY Pp 
AuUKRWHRWNHED 


a 


TMS320C3x/C4x COFF Assembler 
Copyright (c) 1987-1997 


08700080- 
08219866- 
08700080! 
08219800 


o Errors, No Warnings 


Version xX.xx 
Texas Instruments Incorporated 


»text 

. COpy 
-bss 

. COpy 
-global 
-global 
-global 


ldp 
ldi 
ldp 
ldi 


"module2.asm” 
offset, 2 
globals.def 
dflag 
array 
offset 


offset, DP 
@offset, R1 
array, DP 

@array, Rl 


Wed Oct 16 12:00:17 1997 


PAGE 
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Hex Conversion Utility Description 


The TMS320C3x/C4x assembler and linker create object files that are in 
common object file format (COFF), a binary object file format that encourages 
modular programming and provides flexible methods for managing code 
segments. 


Most EPROM programmers do not accept COFF object files as input. The hex 
conversion utility translates a COFF object file into one of several standard 
ASCII hexadecimal formats, suitable for loading into an EPROM programmer. 
The utility is also useful in other applications that require a hexadecimal 
translation of a COFF object file (for example, debuggers and loaders). This 
utility also supports the on-chip boot loader built into the ’C3x or ’C4x, 
automating the code creation process for the 'C3x and ’C4x. 


The hex conversion utility can produce these output file formats: 


_) ASCII-Hex, supporting 16-bit addresses 

_) Extended Tektronix Hexadecimal (Tektronix), supporting 32-bit addresses 
_] Intel MCS-86 Hexadecimal (Intel) supporting 32-bit addresses 

_) Motorola Exorciser (Motorola-S), supporting 16-bit, 24-bit, and 32-bit 

addresses 

_) Texas Instruments SDSMAC (TI-Tagged), supporting 16-bit addresses 
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10.1 Hex Conversion Utility Development Flow 


Figure 10-1 highlights the role of the hex conversion utility in the assembly 
language development process. 


Figure 10-1. Hex Conversion Utility Development Flow 
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10.2 Invoking the Hex Conversion Utility 


Invoking the Hex Conversion Utility From the Command Line 


To invoke the hex conversion utility, enter: 


hex30 [-options] filename 


hex30 is the command that invokes the hex conversion utility. 


-options — supply additional information that controls the hex conversion 
process. You can use options on the commandline or in a com- 
mand file. 


_j All options are preceded by a dash and are not case- 
sensitive. 


.) Several options have an additional parameter that must be 
separated from the option by at least one space. 


(4 Options with multicharacter names must be spelled exactly 
as shown in this document; no abbreviations are allowed. 


4 Options are not affected by the order in which they are 
used. The exception to this rule is the —q option, which must 
be used before any other options. 


filename names a COFF object file or a command file (for more infor- 
mation on command files, see Section 10.3, page 10-6). 


Table 10-1 lists basic options and also bootloader options for the ’C3x and 
’C4x on-chip bootloaders. The bootloader is discussed in more detail on page 
10-28. 


Hex Conversion Utility Description 10-3 


Invoking the Hex Conversion Utility 


Basic Options 


General 
Options 
Control overall 
operation 


Image Options 


Allow you to 
create a continu- 
ous image ofa 
range of target 
memory. 


Memory 
Options 

Allow you to con- 
figure the 
memory widths 
for output files. 


Format Options 
Allow you to 
specify the out- 
put format. 


Option 


—map filename 
-0 filename 
—q 


Option 
—byte 

fill value 
—image 
—zero 
Option 


—datawidth value 


—memwidth 
value 
—order {LS | MS} 


—romwidth value 


Option 


Description 


Generate a map file 
Specify an output filename 


Run quietly (when used, it 
must appear before other 
options) 

Description 

Number bytes sequentially 


Fill holes with value (default 
value =0) 


Specify image mode 


Reset the address origin to 
zero 


Description 


Define the logical data word 
width (default = 32 bits) 


Define the system memory 
word width (default 32) 


Specify the memory 
word ordering 


Specify the ROM 
device width (default de- 
pends on format used) 


Description 
ASCIl-Hex format 
Intel format 
Motorola-S1 format 
Motorola-S2 format 
Motorola-S3 format 
Tl-Tagged format 
Tektronix format 
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Table 10-1. Basic Options (Continued) 


Bootloader Option Description Page 
Options 
Allow you to —boot Convert all sections into boot- 10-29 
control the ’C3x able form (use instead of a 
and ’C4x on-chip SECTIONS directive) 
bootloaders 


—bootorg value Specify the source address of 10-31 
the boot loader table 


—bootpage value Specify the target page num- 10-30 
ber of the boot loader table 


—cg value Set the primary bus global 10-32 
control register (’C31 only) 

—cg value Set the global memory config- 10-37 
uration register (’C4x only) 

—cl value Set the local memory configu- 10-37 
ration register ('C4x only) 

—e value Specify the PC value after 10-31 
loading 

—iack value Specify the IACK memory 10-37 
location (’C4x only) 

—ivtp value Set the interrupt vector table 10-37 
pointer (’C4x only) 

-tvtp value Set the trap vector table point- 10-37 
er (‘C4x only) 

—iostrb value Set the IOSTRB control regis- 10-34 
ter (‘C32 only) 

-strb0 value Set the STRBO control regis- 10-34 
ter (‘C32 only) 

-strb1 value Set the STRB1 control regis- 10-34 


ter (‘C32 only) 
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10.3 Using Command Files 


Using a command file is useful if you plan to invoke the utility more than once 
with the same input files and options. It is also useful if you want to use the 
ROMS and SECTIONS hex conversion utility directives to customize the con- 
version process. 


Command files are ASCII files that contain one or more of the following: 


1 Options and filenames. These are specified in a command file in exactly 
the same manner as on the command line. 


_} ROMSdirectives. The ROMS directive defines the physical memory con- 
figuration of your system as a list of address-range parameters. 


_) SECTIONS directives. The SECTIONS directive specifies which sec- 
tions from the COFF object file should be selected. You can also use this 
directive to identify specific sections that will be initialized by an on-chip 
boot loader. For more information about the ROMS or SECTIONS direc- 
tives, see Section 10.5 or 10.6, respectively. For more information on the 
on-chip boot loader, see Section 10.9, page 10-28. 


(1 Comments. You can add comments to your command file by using the /* 
and */ delimiters. For example: /* this is a comment */ 

To invoke the utility and use the options you defined in a command file, enter: 

hex30 commandfilename 

You can also specify other options and files on the command line. You could 

invoke the utility using both a command file and command line options: 

hex30 firmware.cmd -map firmware.mxp 

The order in which these options and file names appear is not important. The 

utility reads all input from the command line and all information from the 

command file before starting the conversion process. However, if you are us- 


ing the —q option, /t must appear as the first option on the command line or in 
a command file. 


The -q option suppresses the utilityss normal banner and progress 
information. 


hex30 -t firmware -o firm.lsb -o firm.msb 


Creating a Compatible File Format 


10.4 Creating a Compatible File Format 


The hex conversion utility means full flexibility for different memory 
architectures. In order to use the hex conversion utility, you must understand 
how the utility treats word widths. [A word width is the number of bits ina 
word.] Four widths are important in the conversion process: target width, data 
width, memory width, and ROM width. When we refer to these terms, we refer 
to a word of such a width. 


Figure 10-2 illustrates the three separate and distinct phases of the hex 
conversion utility’s process flow. 


Figure 10-2. Hex Conversion Utility Process Flow 


Raw data in COFF files is 

represented in target-width- 
____ sized words. For ’C3x and 

’C4x, this is 32 bits. The 

target width is fixed and 
cannot be changed. 


COFF Input File 


The utility truncates the raw data 
Phase | in the COFF file to the size specified 
by the datawidth option —datawidth 


The 
datawidth-sized internal representation 
is divided into words 
according to the the size specified by —memwidth 
the —-memwiath option. 


Phase Il 


The memwidth- 
sized words are broken up according 
to the size specified by the romwidth 
Phase II option and are written to a file(s) 
according to the format 
specified (Intel, Tektronix hex, etc.). 


—romwidth 


Output File(s) 
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_j) Target Width. Target width is the unit size (in bits) of raw data fields in the 
COFF file. This corresponds to the size of an opcode on the target proces- 
sor. The width is fixed for each target and cannot be changed. The ’C3x 
and ’C4x are 32 bits wide. 


_j Data Width. Data width is the logical width (in bits) of the data words 
stored in a particular section of a COFF file. 


(_} Memory Width. Memory width is the physical width (in bits) of the memory 
system. 


(1 ROM width. The ROM width specifies the physical width (in bits) of each 
ROM device and corresponding output file (usually one byte or eight bits). 


10.4.1 Defining Input Data in the ’C32 


Usually, the data width is the same as the target width. In the ‘C32, however, 
data words can be narrower than the width of the processor. 


Do not change the data width unless you are using the ’C32 processor. 


The ’C32 processor can access values narrower than the processor 
target width. The ’C32 device can access data that is 8, 16, or 32 bits wide. 
The hex conversion utility can extract the appropriate number of bits from the 
COFF file for each data word and store only those bits, even though the COFF 
file uses 32 bits to store each data word. The hex conversion utility simply trun- 
cates the COFF word to the specified length, preserving only the least signifi- 
cant bits of the COFF word. 


You can change the data width by: 

(1 Using the —-datawidth option. This changes the size of data words inside 
all sections in a COFF file. For example, —datawidth 8 changes the size 
of the data words to 8 bits. 

(1 Setting the data width parameter of the SECTIONS directive. This 
changes the size of data words for the specific section and overrides the 


—datawidth option for that section. Refer to Section 10.6 for details. 


Figure 10-3 shows how the data width is related to the target width. 
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Figure 10-3. Target and Data Widths 


Source File .word OAABBCCDDh 
.word 011223344h 


Target Width = 32 (fixed) 
OAABBCCDDh | } row data in COFF file 


011223344h 


Data Widths (variable) 
—datawidth 32 (default) —datawidth 16 —datawidth 8 


eee [an | 
of hex30 11223344 3344 | 44 | 


10.4.2 Specifying the Width 


Usually, the memory system is physically the same width as the target 
processor width: a 32-bit processor has a 32-bit memory architecture. 
However, some applications, such as boot loaders, require target words to be 
broken up into multiple, consecutive, narrower memory words. 


Moreover, with certain processors like the ‘C32, the memory width can be nar- 
rower than the target width. In that case, the hex conversion utility defaults 
memory width to the target width (in this case, 32 bits). 


You can change the memory width by: 


_j) Using the -memwidth option. This changes the memory width value for 
the entire file, or 


_j Setting the memwidth parameter of the ROMS directive. This changes 
the memory width for the address range specified in the ROMS directive 
and overrides the —-memwidth option for that range. See Section 10.5, 
page 10-16. 
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The value used must be a power of two greater than or equal to eight. 


You should change the memory width default value of 32 only in exceptional 
situations: 


Single target words broken into consecutive, narrower memory words. 
Situations in which memory words are narrower than target words are most 
common when you use on-chip boot loaders—several of which support boot- 
ing from narrower memory. For example, a 32-bit TMS320C31 can be booted 
from 8-bit memory, with each 32-bit value occupying four memory locations 
(this would be specified as -memwidth 8). 


Figure 10—4 demonstrates how the memory width is related to the target width. 
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Figure 10-4. Target, Data, and Memory Widths 


Source File 
-word OQOAABBCCDDh 
-word 011223344h 


Data Widths (variable) 


—datawidth 32 (default) —datawidth 16 —datawidth 8 
Data After 
Phase | AABBCCDDh CCDDh DDh 
of hex30 
11223344h 3344h 44h 
Memory Widths (variable) 
Data Width = 32 
—memwidth 32 (default) —memwidth 16 —memwidth 8 
ECDD 
11223344 
Data After 3344 
Phase Il ae 
of hex30 ieee 
Memory Widths (variable) 
Data Width = 16 
—memwidth 32 (default) —memwidth 16 —memwidth 8 
"orca tl CCDD3344 
of hex30 3344 
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10.4.3 Partitioning Data Into Output Files 
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The ROM width determines how the hex conversion utility partitions the data 
into output files. After the target words are mapped to the memory words, the 
memory words are broken into one or more output files. The number of output 
files is determined by the following formula: 


| number of files = memory width — ROM width | 


where memory width > ROM width 


For example, for a memory width of 32, you could specify a ROM width value 
of 32 and get a single output file containing 32-bit words. Or you can use a 
ROM width value of 16 to get two files, each containing 16 bits of each word. 


The default ROM width that the hex conversion utility uses depends on the out- 
put format: 


Lj All hex formats except Tl-Tagged are oriented as lists of 8-bit bytes; the 
default ROM width for these formats is 8 bits. 


(1 TI’s format is 16-bit; the default ROM width for Tl-Tagged format is 16 bits. 


Note: The TI Format is 16 Bits Wide 


You cannot change the ROM width of the Tl-Tagged format. The Tl-Tagged 
format supports a 16-bit ROM width only. 


You can change the ROM width by: 


[1 Using the -romwidth option. This changes the ROM width value for the 
entire COFF file 


1 Setting the romwidth parameter of the ROMS directive. Setting this 
parameter changes the ROM width value for a specific ROM address 
range and overrides the —romwidth option for that range. See Section 
10.5, page 10-16. 


For both, use a value that is a multiple of eight and power of two. 


If you select a ROM width that is wider than the natural size of the output format 
(16 bits for Tl-Tagged or 8 bits for all others), the utility simply writes multibyte 
fields into the file. 


Figure 10-5 illustrates how the target, memory, and ROM widths are related 
to one another. 


Creating a Compatible File Format 


Figure 10-5. Target, Memory, and ROM Widths 


Source File 


-word OQAABBCCDDh 
-word 011223344h 


Data Width = 32 


Data After OAABBCCDDh 
Phase | 


of hex30 011223344h 


Memory Widths (variable) ~~ Le 


/~—memwidth 32\ // ~memwidth 16 
/ \ 
\ 

\ Eze 


Data After == 
Phase II SS 
of hex30 
Output Files 
—romwidth 8 
-0 file.b0 
-0 file.b1 
-0 file.b2 
-0 file.b3 S a 
i 
Ui 
Data After —romwidth 16 7 
Phaselll -o file.wrd CCDDAABB33441122 |//, 
of hex30 ye 
G 
—romwidth 8 Ps 


-0 file.bO DID) iB Ad DBD Vas 
-0 file.b1 CG AA 332 


—romwidth 8 a 
-o file.byt DDCCBBAA4 4332211 |-. 
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10.4.4 A Memory Configuration Example 


Figure 10-6 shows a typical memory configuration example. This memory 
system consists of two 128K x 16-bit ROM devices. 


Figure 10-6. ’C3x/’C4x Memory Configuration Example 


Data Width = 32 Bits 


Lower 16 Bits (data) 


AABBCCDDh< p Upper 16 Bits (data) 


CPU aaa |) eee 
*C3x/’C4x AABBh CCDDh 
128K x 16 128K x 16 
ROMO ROM1 
errs | y V 
| Source File —| birt ae so ta 
| word AABBCCDDh | Its its 
| SS SS SS oa ——<———S- 


System Memory Width 32 Bits 


10.4.5 Specifying Word Order for Output Files 


When memory words are narrower than target words (memory width < 32) tar- 
get words are split into multiple consecutive memory words. There are two 
ways to split a wide word into consecutive memory locations in the same hex 
conversion utility output file: 


(j) -order MS specifies big-endian ordering, in which the most significant 
part of the wide word occupies the first of the consecutive locations 


(1 -order LS specifies little-endian ordering, in which the the least 
significant part occupies the first location 
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By default, the utility uses little-endian format, because the ’C3x/’C4x boot 
loaders expect the data in this order. Unless you are using your own boot load- 
er program, avoid using —order MS. 


Note: When the -order Option Applies 


[__} This option applies only when you use a memory width with a value less 
than 32. Otherwise, the —order is ignored. 


[_] The option does not affect the way memory words are split into output 

files. Think of the files as a set: the set contains a least significant file and 
amost significant file. When you list filenames for a set of files, you always 
list the least significant first, regardless of the —order option. 


Figure 10-7 demonstrates how —order LS and —order MS affect the conver- 


sion process. (This figure, and Figure 10—5, explain the condition of the data 
in the hex conversion utility output files.) 


Figure 10-7. Varying the Word Order 


Source File 


-word QAABBCCDDh 
-word 011223344h 


Target Width = 32 (fixed) 


OAABBCCDDh 
011223344h 


Memory Widths (variable) 


—memwidth 16 —memwidth 16 —memwidth 8 —memwidth 8 
—order LS (default) -—order MS —order LS (default) —order MS 
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10.5 Using the ROMS Directive to Specify Memory Configuration 


The ROMS directive specifies the physical memory configuration of your 
system as a list of address-range parameters. 


Each address range will produce one set of files containing the hex conversion 
utility output data corresponding to that address range. Each file will then be 
used to program a single ROM device. 


The ROMS directive is similar to the MEMORY directive of the TMS320 linker: 
both define the memory map of the target address space. Each line entry in 
the ROMS directive defines a specific address range. The general syntax is: 


ROMS 


[PAGE n°] 
romname: [origin=value,] [length=value,] [romwidth=value,] 
[memwidth=value,] [fill=va/ue,] 
[files={filename 1, filenamed, ...}] 


romname: [origin=value,] [length=value,] [romwidth=value,] 
[memwidth=value,] [fill=va/ue,] 
[files={filename 1, filenamed, ...}] 


ROMS begins the directive definition. 


PAGE identifies a memory space for processors that use multiple 
address spaces or memory overlay pages. Each memory 
range you define after the PAGE command belongs to that 
page until you specify another page. If you don’t include PAGE, 
all ranges belong to page 0. Note that the ’C3x/’C4x processors 
do not offer multiple address spaces. 


romname _ identifies a memory range. The name of the memory range 
may be one to eight characters in length. The name has no 
significance to the program; it simply identifies the range. (Du- 
plicate memory range names are allowed.) 


origin specifies the starting address of a memory range. It may be 
typed as origin, org, or o. The associated value must be a 
decimal, octal, or hexadecimal constant. If you omit the origin 
value, the origin defaults to 0. 
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The following table summarizes the notation you can use to specify a decimal, 
octal, or hexadecimal constant: 


length 


romwidth 


memwidth 


fill 


files 


Constant Notation Example 
Hexadecimal Ox prefix or h suffix 0x77 or 077h 
Octal O prefix 077 

Decimal No prefix or suffix 77 


specifies the length of a memory range as a physical length of 
the ROM device. It may be entered as length, len, or |. The val- 
ue must be a decimal, octal, or hexadecimal constant. If you 
omit the length value, it defaults to fill the rest of the address 
space. 


specifies the physical ROM width of this range in bits (see page 
10-12). Any value you specify here overrides the —romwidth op- 
tion. The value must be a decimal, octal, or hexadecimal 
constant that is a power of two greater than or equal to eight. 


specifies the memory width of this range in bits (see page 
10-9). Any value you specify here overrides the -memwidth 
option. The value must be a decimal, octal, or hexadecimal 
constant that is a power of two greater than or equal to eight. 
When using —memwidth, you must also specify the padadr pa- 
rameter for each section in the SECTIONS directive. 


specifies a fill value to use for this range. In image mode, the 
hex conversion utility uses this value to fill any holes between 
sections in a range. The value must be a decimal, octal, or 
hexadecimal constant with a width equal to the target width. 
Any value you specify here overrides the —fill option. [You must 
also use the —image option when using fill.] See page 10-26. 


identify the names of the output files that correspond to this 
range. Enclose the list of names in curly braces and order them 
from /east significant to most significant output file. 


The number of file names should equal the number of output 
files that the range will generate. The utility warns you if you list 
too many or too few filenames. 


Unless you are using the —image option, all of the parameters defining a range 
are optional. A range with no origin or length defines the entire address space. 
In image mode, an origin and length are required for all ranges. The commas 
and equals signs are also optional. 


Ranges on the same page must not overlap and must be listed in order of 
ascending address. 
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10.5.1 When to Use the ROMS Directive 
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If you don’t use a ROMS directive, the utility defines a single default range that 
includes the entire program address space (PAGE 0). This is equivalent to a 
ROMS directive with a single range without origin or length. 


Use the ROMS Directive when you want to: 


() Program large amounts of data into fixed-size ROMs. When you speci- 
fy memory ranges corresponding to the length of your ROMs, the utility au- 
tomatically breaks the output into blocks that fit into the ROMs. 


(1 Restrict output to certain segments. You can also use the ROMS direc- 
tive to restrict the conversion to a certain segment or segments of the tar- 
get address space. The utility does not convert the data that falls outside 
of the ranges defined by the ROMS directive. Sections can span range 
boundaries; the utility splits them at the boundary into multiple ranges. If 
a section falls completely outside any of the ranges you define, the utility 
does not convert that section and issues no messages or warnings. In this 
way, you can exclude sections without listing them by name with the 
SECTIONS directive. However, if a section falls partially in a range and 
partially in unconfigured memory, the utility issues a warning and converts 
only the part within the range. 


(1 Use the -image option. When you use this option, you must use a ROMS 
directive. Each range is filled completely so that each output file in a range 
contains data for the whole range. Gaps before, between or after sections 
are filled with the fill value from the ROMS directive, with the value speci- 
fied with the —fill option, or with the default value of zero. 
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10.5.2 An Example of the ROMS Directive 


The ROMS directive in Example 10-1 shows how 16K words of 32-bit memory 
could be partitioned for eight 8K x 8-bit EPROMs. 


Example 10-1. A ROMS Directive Example 


[RK KK KK A A A AA AA A I A I a He I / 


/* Sample command file with ROMS directive */ 
[RK KK KK I RI A A A AA AA A A I a He I / 


infile.out 
—image 
—-memwidth 32 


ROMS 
{ 
EPROM1: org = 04000h, len = 02000h, romwidth = 8 
files = { rom4000.b0, rom4000.bl1, 
rom4000.b2, rom4000.b3 } 


EPROM2: org = 06000h, len = 02000h, romwidth = 8, 

fill = OFFh, 

files = { rom6000.b0, rom6000.bl1, 
rom6000.b2, rom6000.b3 } 


In this example, EPROM1 defines the address range from 4000h through 
5FFFh. The range contains the following sections: 


This section Has this range 
.text 4000h through 487Fh 
.data 5B80H through 5FFFh 


The rest of the range is filled with Oh (the default fill value). The data from this 
range is converted into four output files: 


(J rom4000.b0 contains bits 0 through 7 
J rom4000.b1 contains bits 8 through 15 
} rom4000.b2 contains bits 16 through 23 
(J rom4000.b3 contains bits 24 through 31 


EPROM2 defines the address range from 6000h through 7FFFh. The range 
contains the following section: 


This section Has this range 
.data 6000h through 633Fh 
.table 6700h through 7C7Fh 
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The rest of the range is filled with OFFh (from the specified fill value). The data 
from this range is converted into four output files: 


(} rom6000.b0 contains bits 0 through 7 
J rom6000.b1 contains bits 8 through 15 
(} rom6000.b2 contains bits 16 through 23 
(4 rom6000.b0 contains bits 24 through 31 


Figure 10-8 shows how the ROMS directive partitions the infile.out file into 
eight output files. 


Figure 10-8. The infile.out File from Example 10-1 Partitioned Into Eight Output Files 


COFF FILE: OUTPUT FILES: 
infile.out EPROM1 
rom4000.b0 rom4000.b1 rom4000.b2 rom4000.b3 


04000h 04000h 
(org) 
text 
0487Fh 
04880h — 
05B80h Oh 
05B80h 
data 
0633Fh O5FFFh 
06700h Co 
width = 8 bits len = 2000h (8K) ——~ 
EPROM2 


rom6000.b0 rom6000.b1 rom6000.b2 rom6000.b3 
06000h 
06340h 
06700h 


~a 


memwidth = 32 bits 
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10.5.3 Creating Map Files and the —map option 


The map file (specified with the —map option) is very useful when you use the 
ROMS directive with multiple ranges. The map file shows each range, its 
parameters, names of associated output files, and a list of contents (section 
names and fill values) broken down by address. Here’s a segment of the map 
file resulting from the example in Example 10-1. 


Example 10-2. Map File Output from Example 10—1 Showing Memory Ranges 


00004000..00005fff Page=0 Width=8 ”EPROM1” 
OUTPUT FILES: rom4000.b0 [b vil 
rom4000.b1 [b Se 

rom4000.b2 ie -b23] 

rom4000.b3 [b24..b31] 


CONTENTS: 00004000..0000487£ .text 
00004880. .00005b7£ FILL = 00000000 
00005b80..00005fff .data 


CONT 


00006000..00007fff Page=0 Width=8 ”“EPROM2” 
OUTPUT FILES: rom6000.b0 [b 7] 
rom6000.b1 [b ce 

rom6000.b2 ae .b23] 

rom6000.b3 [b24..b31] 


ENTS: 00006000..0000633f .data 


00006340..000066ff FILL = QOOOO0fE 
00006700. .00007c7£ .table 
00007c80..00007f£F FILL = QOOOOOfE 
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10.6 Using the SECTIONS Directive to Convert COFF File Sections 


You may convert specific sections of the COFF file by name with the 
SECTIONS directive. You can also specify those sections you want the utility 
to configure for loading from an on-chip boot loader, and those sections that 
you wish to locate in ROM at a different address than the /oad address speci- 
fied in the linker command file. 


If you: 


(1 Use a SECTIONS directive, the utility converts only the sections that you 
list in the directive; the utility ignores any other sections in the COFF file 
that you don’t specify in the directive. 


(1 Don’tusea SECTIONS directive, the utility converts any initialized section 
that falls within the configured memory. TMS320C3x/C4x compiler- 
generated initialized sections include: .text, .const, and .cinit. 


a a a aaa | 
Note: Sections Generated by the C Compiler 


Uninitialized sections are never converted, whether or not you specify them 
ina SECTIONS directive. TMS320C3x/C4x compiler uninitialized sections 


include: .bss, .stack, and .sysmem. 
a | 


Use the SECTIONS directive in a command file. (For more information about 
using a command file, see Section 10.3, page 10-6.) The general syntax for 
the SECTIONS directive is: 


SECTIONS 

{ 
sname: [paddr=value] [datawidth=value], 
sname: [paddr=boot] 
sname [ = boot ], 


} 
SECTIONS begins the directive definition. 
sname identifies a section in the COFF input file. If you specify a 


section that doesn’t exist, the utility issues a warning and 
ignores the name. 


datawidth=val/ue — specifies the logical width of the data in the section (see 
page 10-8). 
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paddr=value specifies the physical ROM address at which this section 
should be located. This value overrides the section load ad- 
dress given by the linker. (Refer to Section 10.10). This val- 
ue mustbe a decimal, octal, or hexadecimal constant; it can 
also be the word boot to indicate a boot table section for use 
with the on-chip boot loader. [Boot sections have a physical 
address determined both by the target processor type and 
by the various boot-loader-specific command line options.] 
If your file contains multiple sections, and if one section 
uses a —padadr option, then all sections must use a —padadr 
option. 


= boot configures a section for loading by the on-chip boot loader. 
This is equivalent to using paddr=boot. 


The commas are optional. For more similarity with the linker’s SECTIONS 
directive, youcan use colons after the section names and in place of the equals 
sign on the boot keyboard. For example, 


SECTIONS { .text: .data: boot } 


SECTIONS { .text, .data = boot } 


are equivalent. 


For example, suppose a COFF file contains six initialized sections: .text, .data, 
.const, .vectors, .coeff, and .tables. If you want only .text and .data to be con- 
verted, use a SECTIONS directive to specify this: 


SECTIONS { .text, .data } 


To configure both of these sections for boot loading, add the boot keyword: 


SECTIONS { .text = boot, .data = boot } 


a ae | 


Note: Using the —boot Option and the SECTIONS Directive 


When you use the SECTIONS directive with the on-chip boot loader, note 
that the -boot option is ignored. You must explicitly specify any boot sections 
in the SECTIONS directive. For more information about —boot and other 
command line options associated with the on-chip boot loader, see 
Table 10-2, Boot Loader Utility Options, page 10-29. 


|) 
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10.7 Output Filenames 


When the hex conversion utility translates your COFF object file into a data for- 
mat, it partitions the data into one or more output files. When multiple files are 
formed by splitting data into byte-wide or word-wide files, filenames are always 
assigned in order from least to most significant. This is true regardless of target 
or COFF endian ordering, or of any —order option. 


Assigning Output Filenames 
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The hex conversion utility follows this sequence when assigning output file- 
names: 


1) 


It looks for the ROMS directive. If the file is associated with a range in 
the ROMS directive, and you have included a list of files (files = {. . .}) on 
that range, the utility takes the filename from the list. 


For example, assume that the target data is 32-bit words being converted 
to four files, eight bits wide. To name the output files using the ROMS direc- 
tive, you could use specify: 


ROMS 

4 

RANGE1: romwidth=8, files={ xyz.b0O xyz.bl xyz.b2 xyz.b3} 
} 


The utility creates the output files by writing the least significant bits (LSBs) 
to xyz.b0 and the most significant bits (MSBs) to xyz.b3. 


It looks for the -o options. The hex conversion utility often splits the 
target data from the COFF object file on byte, word, or half-word bound- 
aries. It also partitions the data into files of fixed length according to the 
configuration you specify. This results in multiple output files. You can 
specify names for the output files by using the —-o option. The following line 
has the same effect as the example above using the ROMS directive: 


-o xyz.b0O -o xyz.bl -o xyz.b2 -o xyz.b3 
Note that if both the ROMS directive and —o options are used together, the 
ROMS directive overrides the —o options. 


Itassigns a default filename. If you specify no file names or fewer names 
than output files, the utility assigns a default filename. 


Output Filenames 


A default filename consists of the base name from the COFF input file plus a 
2- to 3-character extension. The extension has three parts: 


J A format character, based on the output format: 


a for ASCII-Hex 
i __ for Intel 

t for Tl-Tagged 

m_ for Motorola-S 
x for Tektronix 


(J The range number in the ROMS directive. Ranges are numbered starting 
with 0. If there is no ROMS directive, or only one range, the utility omits 
this character. 


The file number in the set of files for the range, starting with 0 for the least 
significant file. 


For example, assume coff.out is for a 32-bit target processor and you are 
creating Intel-format output. With no output file names specified, the utility pro- 
duces four output files named coff.i0, coff.i1, coff.i2, and coff.i3: 


If you include the following ROMS directive when you invoke the hex 
conversion utility, you would have eight output files: 


ROMS 


range1: o = 1000h 1 = 1000h 
range2: o = 2000h 1 = 1000h 


These Ouiput Files Contain this data 
coff.i00, coff.i01, coff.i02, and coff.i03 1000h through 1FFFh 
coff.i10, coff.i11, coff.i12, and coff.i13 2000h through 2FFFh 
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10.8 Image Mode and the -fill Option 


This section explains the advantages of operating in image mode, and details 
the method of producing output files with a precise, continuous image of a 
target memory range. 


10.8.1 The —image Option 
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With the —image option, the utility generates a memory image by completely 
filling all of the mapped ranges specified in the ROMS directive. 


A COFF file consists of blocks of memory (sections) with assigned memory 
locations. Typically, all sections are not adjacent: there are gaps between 
sections in the address space for which there is no data. When such a file is 
converted without the use of image mode, the hex conversion utility bridges 
these gaps by using the address records in the output file to skip ahead to the 
start of the next section. In other words, there may be discontinuities in the out- 
put file addresses. Some EPROM programmers do not support address dis- 
continuities. 


In image mode, there are no discontinuities. Each output file contains a 
continuous stream of data that corresponds exactly to an address range in tar- 
get memory. Any gaps before, between, or after sections are filled with a fill 
value that you supply. 


An output file converted by using image mode still has address records 
because many of the hex formats require an address on each line. However, 
in image mode, these addresses will always be contiguous. 


So eE—EEOE ee —————————ooo 
Note: Defining the Ranges of Target Memory 


If you use image mode, you must also use a ROMS directive. In image mode, 
each output file corresponds directly to a range of target memory. You must 
define the ranges. If you don’t supply the ranges of target memory, the utility 
tries to build a memory image of the entire target processor address 
space—potentially a huge amount of output data. To prevent this situation, 
the utility requires you to explicitly restrict the address space with the ROMS 


directive. 
| | 
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10.8.2 Specifying a Fill Value 


The -fill option specifies a value for filling the holes between sections. The fill 
value must be specified as an integer constant following the —fill option. The 
width of the constant is assumed to be that of a word on the target processor. 
For example, on the ’'C3x, specifying —fill OFFFFh results in a fill pattern of 
OOOOFFFFh. The constant value is not sign-extended. 


Note: If You Do Not Specify A Value With The Fill Option 


The hex conversion utility uses a default fill value of 0 if you don’t specify a 
value with the fill option. The —fill option is valid only when you use —image; 


otherwise it is ignored. 
Sooo oo SS SSS SS 


10.8.3 Steps to Follow in Image Mode 


Step 1: Define the ranges of target memory with a ROMS directive (see 
Section 10.5). 


Step 2: Invoke the hex conversion utility with the -image option. You can op- 
tionally use the —byte option to number the bytes sequentially and 
the —zero option to reset the address origin to zero for each output 
file. If you don’t specify a fill value with the ROMS directive and you 
want a value other than the default, use the —fill option. 
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10.9 Building a Boot-Table From an On-Chip Boot Loader 


Some DSP devices such as the ’C31, C32, and ’C4x have a built-in boot 
loader that initializes memory with one or more blocks of code or data. The 
boot loader uses a special table (a boot table) stored in memory (such as 
EPROM) or loaded from a device peripheral (such as a serial or communica- 
tions port) to initialize the code or data. The hex conversion utility supports the 
boot loader by automatically building the boot table. 


10.9.1 Description of the Boot Table 


The input for a boot loader is called the boot table (also known as a source 
program). The boot table contains records that instruct the on-chip loader to 
copy blocks of data contained in the table to specified destination addresses. 
Some boot tables also contain values for initializing various processor control 
registers. The boot table can be stored in memory or read in through a device 
peripheral. 


The hex conversion utility automatically builds the boot table for the boot load- 
er. Using the utility, you specify the COFF sections you want the boot loader 
to initialize, the table location, and the values for any control registers. The hex 
conversion utility identifies the target device type from the COFF file, builds a 
complete image of the table according to the format required by that device, 
and converts it into hexadecimal in the output files. Then, you can burn the 
table into ROM or load it by other means. 


Boot loaders support loading from memory that is narrower than the normal 
width of memory. For example, you can boot a 32-bit TMS320C31, 
TMS320C32, or TMS320C40 from a single eight-bit EPROM by using the 
—memwidth option to configure the width of the boot table. The hex conversion 
utility automatically adjusts the table’s format and length. 


10.9.2 The Boot Table Format 
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The boot table format includes a header record containing the width of the 
table and possibly some values for various control registers. Each subsequent 
block has a header containing the size and destination address of the block 
followed by data for the block. Multiple blocks can be entered; a termination 
block follows the last block. Finally, the table can have a footer containing more 
control register values. Refer to the boot-loader section in the specific device 
user’s guide for more information. 
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10.9.3 How to Build the Boot Table 


Table 10-2 summarizes the hex conversion utility options available for the 
boot loader. You can choose from these options in addition to the options listed 
in Table 10-1, page 10-4. 


Table 10-2. Boot-Loader Utility Options 


Option Description 

—boot Convert all sections into bootable form (use instead of a 
SECTIONS directive) 

—bootorg value Specify the source address of the boot loader table 


—bootpage value Specify the target page number of the boot loader table 


—cg value Set the primary bus global control register (‘C31 only) 
—cg value Set the global memory configuration register (’C4x only) 
—cl value Set the local memory configuration register (’C4x only) 
—e value Specify the PC value after loading 

—iack value Specify the IACK memory location (’C4x only) 

—ivtp value Set the interrupt vector table pointer (’C4x only) 

—tvip value Set the trap vector table pointer (’C4x only) 

-iostrb value Set the IOSTRB control register (’C32 only) 

—strbO value Set the STRBO control register (’C32 only) 

-strb1 value Set the STRB1 control register (’C32 only) 


To build the boot table, follow these steps below: 


Step 1: 


Step 2: 


Link the file. Each block of the boot table data corresponds to an 
initialized section in the COFF file. Uninitialized sections are not con- 
verted by the hex conversion utility, see Section 10.6, page 10-22. 


When you select a section for placement in a boot-loader table, the 
hex conversion utility places its load address in the destination 
address field for the block in the boot table. The section content is 
then treated as raw data for that block. 


Identify the bootable sections. You can use the —boot option to tell 
the hex conversion utility to configure all sections for boot loading. 
Or you can use a SECTIONS directive with the utility to select specif- 
ic sections to be configured. Refer to Section 10.6. Note that if you 
use a SECTIONS directive, the -boot option is ignored. 
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Step 3: 


Step 4: 


Step 5: 


Set the ROM address of the boot table. Use the —bootorg option 
to set the source address of the complete table. For example, if you 
are using the ’C4x and booting from memory location 40000000h, 
specify —bootorg 40000000h. The address field in the the hex 
conversion utility output file will then start at 4000000h. 


If you use —bootorg SERIAL or -bootorg COMM, or if you do not use 
the —bootorg option at all, the utility places the table at the origin of 
the first memory range in a ROMS directive. If you do not use a 
ROMS directive, the table will start at the first section load address. 
There is also a —bootpage option for starting the table somewhere 
other than page 0. 


Set boot-loader-specific options, such as entry point, memory 
control registers, as needed. 


Describe your system memory configuration. Refer to Section 
10.4, page 10-7, and Section 10.5, page 10-16 for details. 


The complete boot table is similar to a single section containing all of the head- 
er records and data for the boot loader. The address of this “section” is the boot 
table origin. As part of the normal conversion process, the hex conversion util- 
ity converts the boot table to hexadecimal format and maps it into the output 
files like any other section. 


Be sure to leave room in the memory map for the boot table, especially when 
you are using the ROMS directive. The boot table cannot overlap other non- 
boot sections or unconfigured memory. Usually, this is not a problem; typically, 
a portion of memory in your system is reserved for the boot table. Simply con- 
figure this memory as one or more ranges in the ROMS directive, and use the 
—bootorg option to specify the starting address. 
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10.9.4 Booting From a Device Peripheral 


You can choose to boot from a serial or other port by using the SERIAL or 
COMM keyword with the —bootorg option. Your selection of a keyword de- 
pends on the target device and the channel you want to use. For example, to 
boot a ’C31 or ’C32 from its serial port, specify -bootorg SERIAL on the 
commandline orinacommand file. To boot a TMS320C4x from one of its com- 
munication ports, specify -bootorg COMM. 

a a a CT AES | 
Notes: 


q Possible Memory Conflicts When you boot from a device peripheral, 
the boot table is not actually in memory; it is being received through the 
device peripheral. However, as explained in Step Three, page 10-30, a 
memory address is assigned. 


q Why the System Might Require an EPROM Format for a Peripheral 
Boot Loader Address In atypical system, a parent processor boots a 
a child processor through that child’s peripheral. The boot loader table 
itself may occupy space in the memory map of the child processor. The 
EPROM format and ROMS directive address used correspond to the 


one used by the parent processor, not the one that is used by the child. 
| | 


10.9.5 Setting the Entry Point for the Boot Table 


After completing the boot load process, program execution starts at the 
address of the first block loaded (default entry point). By using the —e option 
with the hex conversion utility, you can set the entry point to a different address. 


For example, if you want your program to start running at address 0123456h 
after loading, specify -e 0123456h on the commandline or in acommand file. 
The value must be a constant; the hex conversion utility cannot evaluate 
symbolic expressions, like c_int00 (default entry point assigned by the 
C compiler). You can determine the —-e address by looking at the map file 
that the linker generates. 


When you use the -e option, the utility builds a dummy block of length 1 and 
data value 0 that loads at the specified address. Your blocks follow this dummy 
block. Since the dummy block is boot-loaded first, the dummy value of 0 is 
overwritten by the subsequent blocks. Then, the boot loader jumps to its ad- 
dress after the boot load is completed. 


10.9.6 Setting Control Registers 


In addition to loading data into memory, some boot loaders can also initialize 
processor control registers from values in the boot table. The hex conversion 
utility provides special options that you can use to set the values for these reg- 
isters. Table 10-3 lists the control register options. Each of these options 
requires a constant value as its argument. 
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Table 10-3. Control Register Options 


Option Register 

-cg value Primary bus global control register (C31 and ’C32 only) 
—cg value Global memory configuration register ('C4x only) 

-cl value Local memory configuration register (’C4x only) 

-iack value IACK memory location (’C4x only) 

-ivtp value Interrupt vector table pointer (’C4x only) 

-tvtp value Trap vector table pointer (’C4x only) 

-iostrb value IOSTRB control register (’C32 only) 

—strb0 value STRBO control register ('C32 only) 

-strb1 value STRB1 control register (‘C32 only) 


10.9.7 Creating a Boot Loader Table for the ’C31 


The ’C31 boot loader has two modes: external memory and serial port. 
External memory can be 8, 16, or 32 bits wide. The serial port assumes 32-bit 
burst mode. The ’C31 can boot multiple blocks, so you can specify more than 
one section to boot. (For detailed information on the ‘C31 boot loader, refer to 
the TMS320C3x User’s Guide.) Furthermore, you can use the —e option to set 
the entry point where execution begins after loading ends. 
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If you are booting from external memory, the boot table has a two-word header: 


(1 The first word defines the width of the memory, which the utility sets to the 
memory width selected. (Refer to Section 10.4, page 10-7.) 


_j The second word is the primary memory configuration register value, 
which you can set with the —-cg option. Because the memory configuration 
register controls how external memory is being accessed, a —cg with an 
incorrect value may cause problems in the boot load process. 


Following the header are blocks of data, each preceded with a size and des- 
tination address. A size field of 0 terminates the list. If the memory width is less 
than 32, the data must be ordered from least to most significant. The 
conversion utility automatically builds the table in the correct format. 


To configure one or more sections to boot from external memory, link each sec- 
tion with a load address equal to its destination address. Refer to page 10-29 
for details on the basic steps to follow to build a boot-loader table. 
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Booting From a Serial Port 


Booting from the serial port is similar to booting from external memory. Here, 
however, you specify —bootorg SERIAL. In serial mode, the two-word boot 
table header is omitted and the table immediately starts with the size of the first 
block. Refer to page 10-31. 


An Example: Booting the ‘C31 From Memory 


Suppose you want to boot the ’C31 from a 16-bit memory system at location 
1000h with the following conditions: 


_) The 16-bit memory system consists of two side-by-side 8K x 8-bit 
EPROMs, specified in the ROMS directive. 


(4 You have three sections to load: .text, .cinit, and .const, specified in the 
SECTIONS directive. 


_) You want the program to start running at address 0809802h after loading 
(use —e 0809802h). 


_) You want to set the primary bus control register to zero wait-states, no 
bank switching and external ready. 


Example 10-3 uses the ROMS directive to define the EPROMs as memory 
ranges and the —image option to fill all 8K locations of each output file. 


Example 10-3. Using the TMS320C31 Boot Loader 


[BKK KK KK KK A AR A I A A AA AA A A I A A I I / 


/* Sample command file for C31 EPROM Boot Sy 
[KOK KKK KK A A AA A A A A AA AA A A a A I A / 
abc.out /* input file */ 
-i /* Intel format * f 
—memwidth 16 /* 16-bit memory system ef 
-bootorg 1000h /* location of the external boot memory #y 
-cg Oh /*primary bus configuration * / 
ROMS 


{ 
EPROM: org = 01000h, len = 02000h, romwidth = 8,/* 8K x 8 af 
files = { abc.lsb, abc.msb } 
} 


SECTIONS { .text: BOOT, .cinit: BOOT, .const: BOOT } 


This example produces two output files, one for each EPROM, each contain- 
ing 8-bit wide data. If you want a single output file with all 16 bits (one single 
8K x 16-bit ROM device used), use ROMwidth=16 instead of ROMwidth = 8. 


Hex Conversion Utility Description 10-33 


Building a Boot-Table From an On-Chip Boot Loader 


10.9.8 TMS320C32 Boot Loader Table Generation 


The ’C32 boot loader has two modes: external memory and serial port. Exter- 
nal memory can be 8, 16, or 32 bits wide. The serial port assumes 32-bit burst 
mode. The ’C32 can boot multiple blocks, so you can specify more than one 
section to boot. Furthermore, you can use the -e option to set the entry point 
where execution begins after loading ends. For more detailed information on 
the ’C32 boot loader, refer to the TMS320C3x User’s Guide and the ‘C32 
User’s Guide. 


Booting From External Memory 
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If you are booting from external memory, the boot table has a four-word 

header: 

(1 The first word defines the width of the memory system, which the utility 
sets to the memory width selected, as explained in Section 10.4, page 
10-7. 


[4 The second word is the configuration value for the IOSTRB control 
register, which you can set with the —iostrb option. 


(1 The third word is the configuration value for the STRBO control register, 
which you can set with the —strb0 option. 


(1 The fourth word is the configuration value for the STRB1 control register, 
which you can set with the —strb1 option. 


Following the header are blocks of data, each block preceded with a header 
that defines a size, a destination address, and a strobe-control register value. 
A size field of zero terminates the list. If the memory width is less than 32, the 
data is ordered from least to most significant. If the data width is less than 32 
for any section in the boot table, only the least significant datawidth bits are 
stored in the output files. The conversion utility automatically builds the table 
in the correct format. 


To configure one or more sections to boot from external memory, link each sec- 
tion with a load address equal to its destination address. Refer to page 10-29 
for the steps required in boot-loader table generation. 


If there are multiple data widths in the boot table, you can use the data width 
parameter of the SECTIONS directive to specify data width, or the —-datawidth 
option to specify the global data width. The data width for any section con- 
taining code or address values must always be set to 32. Otherwise, the 
boot loading process may fail. 
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Booting From a Serial Port 


Booting from the serial port is similar. Specify —bootorg SERIAL. In serial 
mode, the first word of the boot table header is omitted and the table 
immediately starts with the configuration value for the IOSTRB control register. 


Booting the ’C32 from Memory 


Suppose you want to boot the C32 from 16-bit memory at location 1000h with 
the following conditions: 


_) The 16-bit memory consists of two side-by-side 8K x 8 EPROMs, specified 
in the ROMS directive. 


Lj You have four sections to load: 


Section Data width 
.text 32 

.cinit 32 

.const 32 
.userdata 8 


Lj The program will start running at 0809802h after loading (use —e 
0809802h). 


_} You want to set the IOSTRB global control register to 0 wait state 


_} You want to set STRBO to 0 wait state, no bank switching, external ready, 
and 32-bit data width in 32-bit wide memory 


_) You want to set STRB1 to 0 wait state, no bank switching, external ready 
and 8-bit data in 8-bit wide memory. 


Example 10—4 shows a command file that uses the ROMS directive to define 
the EPROMs as amemory range and the —image option to fill all 8K locations 
of each output file. 
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Example 10-4. Using the TMS320C32 Boot Loader 


[ORK KK IK KK KI IA IA A A A AA A I A A I I A / 


/* Sample command file for C32 EPROM Boot aed 
[BORK KK KKK KK KA IA A IA AA A I A A A I I I / 
abc.out /* input file vA 
-i /* Intel format */ 
—memwidth 16 /* 16-bit memory yy 
-bootorg 1000h /* external memory boot my, 
-iostrb Oh /* IOSTRB configuration */ 
-strb0O OFO0000h /* STRBO configuration * ff 
-strbl1 050000h /* STRB1 configuration af 
ROMS 


{ 
EPROM: org = 01000h, len = 02000h, romwidth = 8,/* 8K x 8 */ 
files = { abc.lsb, abc.msb } 


} 


SECTIONS { 
.text: BOOT 
-cinit: BOOT 
-const: BOOT 
-userdata: BOOT 
datawidth = 8 


This example produces two output files, one for each EPROM, each contain- 
ing 8-bit wide data. If you want a single output file with all 16 bits, use 
ROMwidth = 16 instead of ROMwicdth = 8. 
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10.9.9 TMS320C4x Boot Loader Table Generation 


The ’C4x boot loader can boot through either external memory or one of the 
communication ports. External memory can be 8, 16, or 32 bits wide. The com- 
munication ports are 8-bit channels that use internal buffering to effect 32-bit 
transfers. The ’C4x can boot multiple blocks, so you can specify more than one 
section to boot. Furthermore, you can use the —e option to set the entry point 
where execution begins after loading ends. Refer to the TMS320C4x User's 
Guide for details on boot loader operation. 


Booting From External Memory 
The boot table has a three-word header: 


_] The first word defines the width of the memory, which the utility sets to the 
memory width value. See Section 10.4. 


_j) The second and third words are the configuration values for global and 
local memory, which you can set with the -cg and —cl options, respectively. 


Following the header are blocks of data, each preceded with a size and des- 
tination address. A size field of 0 terminates the list. Following the table are 
three more configuration values for the IVTP register, TVTP register, and |ACK 
memory location. You can set these with the —ivtp, —tvtp, and —iack options. 
If the memory width is less than 32, the partial words are ordered from least 
to most significant. The hex conversion utility automatically builds the table in 
the correct format. 


To configure one or more sections to boot from external memory, link each 
section with a load address equal to its destination address. Refer to page 
10-29 for the basic steps to follow when building a boot loader table. For in- 
formation on how to describe your external memory system, refer to Section 
10.7, page 10-24. 


Booting From a Communications Port 


Booting from a communications port is similar to booting from external 
memory. Simply specify -bootorg COMM. In comm port mode, the first word 
of the boot table header (the memory width) is omitted. Refer to page 10-31 
for more information. 
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An Example: Booting a ’C4x From a Communications Port 


Suppose you want to boot a ’C4x child processor from a communications port 
connected to a parent C4x processor. The following conditions apply: 


L 


Ly 


You want to set the child global memory control register to a 1D78C9FOh 
value. 


You want to set the child local memory control register to a 1D739250h 
value. 


You wantto set the location of the interrupt vector table and the trap vector 
table of the child processor in location 2ff800h. 


You want all of the initialized sections to boot automatically (use —boot). 


You want the program to start running in the child processor at 40000000h 
after loading (use —e 40000000h). 


The parent processor will have the child boot loader table information 
stored in its own memory at address 0x300000 (one single eight-bit ROM 
device) 


The command file is shown in Example 10-5. 


Example 10-5. Using the ’'C4x Boot Loader 


abc.out 

-o abc.i 

-i 

-memwidth 8 
—-romwidth 8 
-boot 

-bootorg COMM 
-cg 01D7BC9FOh 
-cl 01D739250h 


-ivtp O02FF800h 
-tvtp O02FF800h 
-iack 0300000h 
ROMS 

{ 


} 


/* 
/* 


[KK HK KK KR KR AR AR AR AA AR A IR A A A I A A A A A A I A I a a I / 
/* Sample command file for C40 COMM Boot a] 
[KK HK KK KK KR RR AR AR A A AA A A A I A I A A A I A A A A A I I  / 
input file (child processor executable) */ 
output file (parent processor ROM) * / 
Intel format (parent processor) */ 
parent processor memory system width * / 
physical width of each ROM device */ 
boot all initialized sections of the child processor */ 
boot from comm port (child processor) ay 
global memory config (child processor) + 
local memory config (child processor) * / 
IVTP initializer (child processor) */ 
TVTP initializer (child processor) A 
IACK memory location (child processor) Pay: 
len = 2000h /* parent memory * / 


EPROM: org= 0300000h, 
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This example produces a single file, called abc.i, to be burned in the parent 
processor EPROM, with alist of bytes; four per word. If you want the file to con- 
tain 32-bit words instead, use -memwidth 32 and —-romwidth 32. 
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10.10 Controlling the ROM Device Address 


10.10.1 


The hex conversion utility output address field corresponds to the ROM device 
address. The EPROM programmer burns the data in the location specified by 
the hex conversion utility output file address field. The hex conversion utility 
offers some mechanisms to control the starting address in ROM of each sec- 
tion and/or control the address index used to increment the address field. How- 
ever many EPROM programmers offer direct control of the location in ROM 
in which the data is burned. 


Controlling the Starting Address 


Depending on the condition of the boot loader, the the hex conversion utility 
output file controlling mechanisms are different. 


LJ Non Boot-loader mode 


The address field of the hex conversion utility output file is controlled by the 
following mechanisms listed from low to high priority: 


1. The linker command file: 


By default, the address field of a the hex conversion utility output file 
is a function of the load address (as given in the linker command file) 
and the hex conversion utility parameter values. The relationship is 
summarized as follows: 


out_file_addrt = load_addr x (data_width — mem_width) 


out_file_addr The address of the output file. 
load_addr The linker-assigned load address 


data_width Data width can be specified by the —datawidth 
command or the datawidth option inside the 
SECTIONS directive. See Section 10.4. 

mem_width The memory width of the memory system. You 
can specify the memory width by the -memwidth 
command or the memwidth option inside the 
ROMS directive. See Section 10.4. 


Tt If paddr is not specified 


Consider the value of data width divided by memory width a 
correction factor for address generation. If data width is larger than 
memory width, then the correction factor expands the address 
space. 
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For example, if the load address is 0x1 and datawidth divided by 
memory width is 4, the output file address field would be 0x4. The 
data is split into four consecutive locations of size memory width. 


When data width is less than memory width, then the correction fac- 
tor compresses the address space. 


For example, assume that a section in the COFF input file contains 
four words of 8-bit data width with linker-assigned load addresses of 
0x0, 0x1, 0x2, and 0x3, respectively. If memory width is equal to 32, 
then data width divided by memory width is equal to 1/4. Therefore, 
the four 8-bit data words will be packed into one single 32-bit memory 
word with an address of Ox0. (Notice that the address is truncated 
to an integer.) 


2. The —paddr option inside the SECTIONS directive: 


When —paddr is specified for a section, the hex conversion utility by- 
passes the section load address and places the section in the 
address specified by —-paddr. The relation between the hex conver- 
sion utility output file address field and -paddr can be summarized 
as follows: 


out_file_addrt = paddr_val + ( load_addr — sect_beg_load_addr ) x (data_width — mem_width) 
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out_file_addr The address of the output file 


paddr_val The value supplied with the -paddr option inside 
the SECTIONS directive 


sec_beg_load Section beginning load address assigned by 
_addr linker 


tit padadr is specified 


The value of data width divided by memory width is a correction fac- 
tor for address generation. The load address — section beginning 
load address factor is an offset from the beginning of the section. 


3. The zero option 


When you use the —zero option, the utility resets the address origin 
to zero for each output file. Since each file starts at zero and counts 
upward, any address records represent offsets from the beginning 
of the file (the address within the ROM) rather than actual target ad- 
dresses of the data. 


You must use this option in conjunction with the —image option to 
force the starting address in each output file to be zero. If you specify 
the —zero option without the —image option, the utility issues a warn- 
ing and ignores the option. 
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_) Boot-Loader Mode 


In the boot-loader case, the hex conversion utility places the different 
COFF sections inside the boot loader table in consecutive memory loca- 
tions. Each COFF section becomes a boot loader table block whose des- 
tination address is equal to the section linker-assigned load address. 


The address field of the the hex conversion utility output file is not related to 
the section load addresses assigned by the linker. The address fields are 
simply offsets to the beginning of the table, multiplied by the correction fac- 
tor (data width divided by memory width, as previously explained.) 


The beginning of the boot loader table defaults to the linked load address 
of the first bootable section in the COFF input file, unless you use one of 
the following mechanisms, listed here from low- to high-priority. Higher 
priority mechanisms override the values set by low priority options in the 
overlapping range. 


1. The ROM origin specified in the ROMS directive: 


The hex conversion utility places the boot loader table at the origin 
of the first memory range in a ROMS directive. 


2. The -bootorg option: 


The hex conversion utility places the boot loader table at the address 
specified by the —bootorg option if you select boot loading from 
memory. Neither -bootorg COMM nor —bootorg SERIAL affect the 
address field. 


10.10.2 Controlling the Address Increment Index 


By default, the hex conversion utility increments the output file address field 

based on memory width value. If the memory width equals 16 bits, the address 

will increment based on how many 16-bit words are present in each line of the 

output file. 

LJ The -byte option 
Some EPROM programmers may require the address field of the hex con- 
version utility output file increments in a byte basis. If you use the —byte 
option, the output file address is incremented once for each byte. In an ex- 
ample in which the starting address is Oh and the first line contains eight 
words, with —byte, the second line would start at address 32 (020h). The 
data is the the same; —byte affects only the calculation of the output file 
address field, not the actual target processor address of the converted 
data. 


The —byte option causes the address records in an output file to refer to 
byte locations within the file, whether the target processor is byte- 
addressable or not. 
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10.10.3 Dealing With Address Holes 


When memory width is different from data width, the automatic multiplication 
of the load address by the correction factor might create holes at the beginning 
of a section or between sections. 


For example, assume you wanted to load a COFF section (.sec1) at address 
0x0100 of an 8-bit EPROM. If you specify the load address in the linker com- 
mand file at location 0x100, the hex conversion utility will multiply the address 
by four (data width divided by memory width = 32/8 = 4), giving the output file 
a starting address of 0x400. Unless you control the starting address of the 
EPROM with your EPROM programmer, you could create holes within the 
EPROM. The EPROM will burn the data starting at location 0x400 instead of 
0x100. You can solve this by: 


(1 Using the paddr command parameter of the SECTIONS directive. 


This forces a section to start at the provided value. Example 10-6 shows a 
hex command file that can be used to avoid the hole at the beginning of 
sect. 


Example 10-6. Hex Command File For Hole Avoidance 
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=a 
a.out 


—map a.map 


ROMS 
{ 


ROM : org = 0x0100, length = 0x200, romwidth = 8, memwidth = 8, 


} 


SECTIONS 
{ 


secl: 


paddr = 0x100 


Note: Conditions for Using the paddr Parameter 


If one section uses a paddr parameter, then all sections must use the paddr 
parameter. 


| 


_) Using the bootorg command line, or using the ROMS origin option 


As described on page 10-42, the EPROM address of the entire boot-load- 
er table can be controlled by the -bootorg option or by the ROMs directive. 


Description of the Object Formats 


10.11 Description of the Object Formats 


The hex conversion utility converts a COFF object file into one of five object 
formats that most EPROM programmers accept as input: ASCII-Hex, Intel 
MCS-86, Motorola-S, Extended Tektronix, and Tl-Tagged. This section de- 
scribes each object format. 


You can use one of the options in Table 10-4 to specify the hex format you 
want to use for the output files. 


_j If you use more than one of these options, the last one you list overrides 
the others. 


_j The default output format is Tektronix (—x option). 


Table 10-4. Options for Specifying Hex Conversion Formats 


Address Default 

Option Format Bits Width 
-a ASCIl-Hex 16 8 

-i Intel 32 8 
—m1 Motorola-S1 16 8 
—m2or—m_ Motorola-S2 24 8 
—m3 Motorola-S3 32 8 

-t Tl-Tagged 16 16 
—Xx Tektronix 32 8 


Address bits determine how many bits of the address information the format 
supports. The formats with 16-bit addresses only support addresses up to 
64K. The utility truncates target addresses to fit in the number of bits available. 


The default width determines the default output width of the format. You can 
change the default width by using the -romwidth option or by specifying the 
—romwidth option in the ROMS directive. You cannot change the default width 
of the Tl-Tagged format. The Tl-Tagged format supports a 16-bit width only. 


———S—SSSSSSSSSESESNSSESESSSSSEeeeeeeeeeeeeooeoeeeeeeeeeeeeeeeeeeSeeSS—S—S———S—s—as—SsSssasaoo=— 
Note: Using the Intel Format 


The Intel format has been extended to support 32-bit addresses. Special lin- 
ear address records (record type = 04h) are used to represent the upper 16 


bits of any address requiring more than 16 bits. 
ee 
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10.11.1 ASCIl-Hex Object Format (—a Option) 


The ASCII-Hex object format supports 16-bit addresses. The format consists 
of a byte stream with bytes separated by spaces. Figure 10-9 illustrates the 
ASCIl-Hex format. 


Figure 10-9. ASCII-Hex Object Format 


Nonprintable 


Nonprintable Address End Code 
Start Code] 
ro | 
“B SAXXXX, 
XX XX XX XX XX XX XX XX XX XX. . .*C 
Data Byte 


The file begins with an ASCII STX character (ctrl-B, 02h) and ends with an 
ASCII ETX character (ctrl-C, 03h). Address records are indicated with 
$AXXXX, where XXXxX is a four-digit (16-bit) hexadecimal address. The ad- 
dress records are present only in the following situations: 


[J When discontinuities occur 


1 When the byte stream does not begin at address 0 


You can avoid all discontinuities and any address records by using the —-image 
and —zero options. This creates output that is simply a list of byte values. 
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10.11.2 Intel MCS-86 Object Format (-—i Option) 


The Intel object format supports 16-bit addresses and 32-bit extended 
addresses. Intel format consists of a nine-character (four-field) prefix, which 
defines the start of record, byte count, load address, and record type, and a 
two-character checksum suffix. 


The 9-character prefix represents three record types: 


Record Type Description 


00 Data record 
01 End-of-file record 
04 Extended linear address record 


Record type 00, the data record, begins with a colon (:) andis followed by the 
byte count, the address of the first data byte, the record type (00), and the 
checksum. Note that the address is the least significant 16 bits of a 32-bit ad- 
dress; this value is concatenated with the value from the most recent 04 
(extended linear address) record to create a full 32-bit address. The checksum 
is the 2s complement (in binary form) of the preceding bytes in the record, in- 
cluding byte count, address, and data bytes. 


Record type 07, the end-of-file record, also begins with a colon (: ), followed 
by the byte count, the address, the record type (01), and the checksum. 


Record type 04, the extended linear address record, is used to specify the 
upper 16 address bits. It begins with a colon ( : ), followed by the byte count, 
adummy address of Oh, the record type (04), the most significant 16 bits of the 
address, and the checksum. The subsequent address fields in the data re- 
cords contain the least significant bits of the address. 


Figure 10-10 illustrates the Intel hex object format. 


Figure 10-10. Intel Hex Object Format 


Address Most Significant 16 Bits 


Start — Checksum 
Character (4 oe 
> 02000004FFEEEO “+ Extended Linear 
:10334400112233445566778899FFFFFFFFFFFFFFFF | Address Record 
:LOOOQOQOOOFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFOO ; 
:10001000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEFO ;— ome 
:LOOOZ000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEO 
:LOOO3000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFDO_ , 
LC J>__ End-of-File 
:0Q000001 FE — — Record 
Byte — | LL Checksum 
Count Record 
Type 
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10.11.3  Motorola-S Object Format (—m1, —m2, —m3 Options) 


Figure 10-11. 
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The Motorola S1, S2 and S3 formats support 16-bit (S1), 24-bit (S2), and 32-bit 
(S3) addresses. The formats consist of a start-of-file (header) record, data re- 
cords, and an end-of-file (termination) record. Each record is made up of five 
fields: record type, byte count, address, data, and checksum. The record types 
are: 


Record Type Description 

SO Header record 

$1 Code/data record for 16-bit addresses (S1 format) 
$2 Code/data record for 24-bit addresses (S2 format) 
$3 Code/data record for 32-bit addresses (S3 format) 
S7 Termination record for 32-bit addresses (S3 format) 
S8 Termination record for 24-bit addresses (S2 format) 
Sg Termination record for 16-bit addresses (S1 format) 


The byte count is the character pair count in the record, excluding the type and 
byte count itself. 


The checksum is the least significant byte of the 1s complement of the sum 
of the values represented by the pairs of characters making up the byte count, 
address, and the code/data fields. 


Figure 10-11 illustrates the tag characters in Motorola-S object formats. 


Motorola-S Format 


Type 
S00B00004441544120492F4FF3 ~L Header 


S1130000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEC 5 cae 
S1130010FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFED Data 
S1130020FFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFEFDC T Records 
S1130030FFFFFFFFFFFFFFFFFFFFFFFFFEFFFFFFEFCC 
S1130040FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEEBC — 


S9030000FC |. Termination 
Ji) — Record 
Byte T |__ Checksum 
Count 
Address 


10.11.4 Tl-Tagged 
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Object Format (-t Option) 


The Tl-Tagged object format supports 16-bit addresses. It consists of a start- 
of-file record, data records, and end-of-file record. Each of the data records is 
made up of a series of small fields and is signified by a tag character. The sig- 
nificant tag characters are: 


Tag Character Description 


followed by the program identifier 
followed by a checksum 


followed by a dummy checksum (ignored) 
followed by a 16-bit load address 
followed by a data word (four characters) 


10 OO NX 


identifies the end of a data record 


followed by a data byte (two characters) 


Figure 10-12 illustrates the tag characters in Tl-Tagged object format. 


Figure 10-12. Tl-Tagged Object Format 


Program 
Identifier Tag Characters 


| 
| | 
| a aI 
KOOOCdFFTOTI l ] l ] ] C] fl =a 
S9O0000BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBFFFF/F234F 


90020BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBEFFFFBEFFFF/F400F Data 
90040BFFFFBFFFFBFFFFBFFFFBFFFFBFFFFBEFFFFBEFFF/F3FFF Records 


OER Oe eee ee ene kere ene. | 
. fi 


- 


l I I | | 
Load Data Checksum 


End of File Address Words 


Record 


In the example above, each of the lines begin with a load address. Note that 
this is not always the case; a line can begin with a data word (specified by the 
B tag). 


If any data fields appear before the first address, the first field is assigned ad- 
dress 0000h. Address fields may be expressed for any data byte, but none is 
required. The checksum field, which is preceded by the tag character 7, is a 
2s complement of the sum of the 8-bit ASCII values of characters, beginning 
with the first tag character and ending with the checksum tag character (7 or 
8). The end-of-file record is a colon (: ). 
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10.11.5 Extended Tektronix Object Format (—x Option) 


The Tektronix object format supports 32-bit addresses and has two types of 
records: 


data record contains the header field, the load address, and the 
object code. 


termination record signifies the end of a module. 


The header field in the data record contains the following information: 


Number of 
ASCII 
Item Characters Description 
% 1 Data type is Extended Tektronix hex format 
Block 2 Number of characters in the record, minus the % 
length 
Block type 1 6 = data record 
8 = termination record 
Checksum 2 A two-digit hex sum modulo 256 of all values in the 


record except the % and the checksum itself. 


The load address in the data record specifies where the object code will be 
located. The first digit specifies the address length; this is always 8. The re- 
maining characters of the data record contain the object code, two characters 
per byte. 


Figure 10-13 illustrates the Tektronix object format. 


Figure 10-13. Extended Tektronix Hex Object Format 


Checksum: 21h = 1+5+6+8+1+0+0+0+0+0+0+0+ 
2+0+2+0+2+0+2+0+2+0+2+0 


Block Length 


15h = 21 I ~—— Object Code: 6 bytes 
rac et aad 
Header __§15621810000000202020202020 


Character | | 


L__ Load Address: 10000000h 
Block Type: Length of 
6 (data) Load Address 


10-48 


Hex Conversion Utility Error Messages 


10.12 Hex Conversion Utility Error Messages 


section mapped to reserved memory message 


Description A section or a boot-loader table is mapped into a reserved 


Action 


memory area as listed in the processor memory map. 


Correct section or boot-loader address. For valid memory loca- 
tions, refer to the user’s guide for the specific processor . 


sections overlapping 


Description Two or more COFF section load addresses overlap or a boot 


Action 


table address overlaps another section. 


This problem may be caused by an incorrect translation from 
load address to hex output file address that is performed by the 
hex conversion utility when memory width is less than data 
width. Refer to Section 10.4, page 10-7 and Section 10.10, 
page 10-39. 


unconfigured memory 


Description This error could have one of two causes: 


Action 


Mm The COFF file contains a section whose load address falls 
outside the memory range defined in the ROMS directive. 


m@ The boot-loader table address is not within the memory 
range defined by the ROMS directive. 


Correct your ROM range as defined in your ROMS directive to 
cover the memory range as needed, or modify the section load 
address or boot-loader table address. Remember that if the 
ROMS directive is not used, the memory range defaults to the 
entire processor address space. For this reason, removing the 
ROMS directive could also be a workaround. 
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Common Object File Format 


The TMS320C3x/C4x assembler and linker create object files that are in com- 
mon object file format (COFF). COFF is an implementation of an object file for- 
mat of the same name that was developed by AT&T for use on UNIX-based 
systems. This object file format has been chosen because it encourages mod- 
ular programming and provides more powerful and flexible methods for man- 
aging code segments and target system memory. 


One of the basic COFF concepts is sections. Chapter 2, Introduction to Com- 
mon Object File Format, discusses COFF sections in detail. If you understand 
section operation, you will be able to use the TMS320 assembly language 
tools more efficiently. 


This appendix contains technical details about COFF object file structure. 
Most of this information pertains to the symbolic debugging information that 
is produced by the TMS320C3x/C4x C compiler. The main purpose of this ap- 
pendix is to provide supplementary information for those of you who are inter- 
ested in the internal format of COFF object files. 


Topics in this appendix include: 


Topic Page 
A.1_ How the COFF File Is Structured ..........0..0.c0seeeeeeeeeeees 
Al2)) Fileil Cader: Structure ere terete clei istelel relist ee ecto etereietereyeie ts teelerey = a-5] 
A.3 Optional File Header Format .............:000 cece e eee eee eee 
ACA Soctlon Header Situctute aencscr ccid.wen tees cece cuerceeesan 
A.5 Structuring Relocation Information ..............2..000eeeeeeee A-10 
A.6  Line-Number Table Structure .............00cceeeeeeeee eee e eee A-12 
A.7 Symbol Table Structure and Content ................002eeeeeee A-14 
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A.1 How the COFF File Is Structured 


The elements of a COFF object file describe the file’s sections and symbolic 
debugging information. These elements include: 


A file header 

Optional header information 

A table of section headers 

Raw data for each initialized section 

Relocation information for each initialized section 
Line number entries for each initialized section 

A symbol table 

A string table 


OOOO Oo oo 


The assembler and linker produce object files with the same COFF structure; 
however, a program that is linked for the final time will not contain relocation 
entries. Figure A—1 illustrates the overall object file structure. 


Figure A-1. COFF File Structure 


file header 


optional file header 


section 1 header 


section headers 


section n header 


section 1 
raw data 
raw data 
(executable code 
section n and initialized data) 
raw data 
section 1 
relocation information 
relocation 
5 information 
section n 
relocation information 
section 1 
line numbers 
line number 
entries 


section n 
line numbers 


symbol table 


string table 
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How the COFF File is Structured 


Figure A—2 shows a typical example of a COFF object file that contains the 
three default sections, .text, .data, and .bss, and a named section (referred to 
as <named>). By default, the tools place sections into the object file in the fol- 
lowing order: .text, .data, initialized named sections, .oss, and uninitialized 
named sections. Although uninitialized sections have a section headers, they 
have no raw data, relocation information, or line number entries. This is be- 
cause the .bss and .usect directives simply reserve space for uninitialized 
data; uninitialized sections contain no actual code. 


Figure A-2. Sample COFF Object File 


file header 


.text 
section header 


data 
section header 


.bss 
section header 


section headers 


<named> section 
section header 


.text 
raw data 


data 
raw data raw data 


<named> section 
raw data 


.text 
relocation information 


data : relocation 
relocation information information 


<named> section 
relocation information 


.text 
line numbers 


data line number 
line numbers entries 


<named> section 
line numbers 


symbol table 


string table 
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A.1.1_ Impact of Switching Operating Systems 


The TMS320C3x/C4x COFF files are recognized by all operating system ver- 
sions of the development tools. When you switch from one operating system 
to another, only the file header information in the COFF files needs to be byte 
swapped. The raw data in the COFF files does not need any changes. 


The development tools can detect the difference in the file headers and auto- 
matically compensate for it. This is true if using only TMS320C3x/C4x devel- 
opment tools. 


To tell the difference between COFF files, you can look at the magic number 
in the optional file header. Bytes 0 and 1 contain the magic number. For the 
SunOS™ or HP-UX™ operating systems, the magic number is 108h. For the 
DOS operating system, the magic number is 801h. 
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File Header Structure 


The file header contains 20 (COFF 0) or 22 (COFF 1 and 2) bytes of informa- 
tion that describe the general format of an object file. Table A-1 shows the 
structure of the file header. 


Table A—1. File Header Contents 


Byte 
Numbers 


0-1 


2-3 
4-7 


18-19 
20-21 


Type 


Unsigned short integer 


Unsigned short integer 


Long integer 


Long integer 


Long integer 


Unsigned short integer 


Unsigned short integer 


Unsigned short integer 


Description 


COFF 0: Contains magic number (093h) to 
indicate the file can be executed in a 
TMS320C3x/C4x system. 


COFF 1 and 2: Contains COFF version 
number, either Octh (COFF1) or Oc2h 
(COFF 2) 


Number of section headers 


Time and date stamp; indicates when the file 
was created 


File pointer; contains the symbol table’s 
starting address 


Number of entries in the symbol table 


Number of bytes in the optional header. This 
field is either 0 or 28; if itis 0, there is no op- 
tional file header. 


Flags (see Table A—2) 


Included for COFF 1 and 2 only. Contains 
magic number (093h) to indicate the file 
can be executed in a TMS320C3x/C4x 
system. 


Table A-2 lists the flags that can appear in bytes 18 and 19 of the file header. 
Any number and combination of these flags can be set at the same time (for 
example, if bytes 18 and 19 are set to 0003h, F_RELFLG and F_EXEC are 


both set). 
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Table A—2. File Header Flags (Bytes 18 and 19) 
Mnemonic _ Flag Description 
F_VERSO 0000h TMS320C30/C31 object code 
F_RELFLG 000th Relocation information was stripped from the file 


F_EXEC 0002h The file is executable (it contains no unresolved external 
references) 


F_LNNO 0004h Line numbers were stripped from the file 
F_LSYMS 0008h Local symbols were stripped from the file 
F_VERS1 0010h TMS320C40/C44 object code 

F_VERS2 0020h TMS320C32 object code 

F_LITTLE 0100h Object data LSB first 


A.3 Optional File Header Format 


The linker creates the optional file header and uses it to perform relocation at 
download time. Partially linked files do not contain optional file headers. 
Table A—3 illustrates the optional file header format. 


Table A—3. Optional File Header Contents 


Byte 
Number Type Description 

0-1 Short integer Magic number (0108h) 

2-3 Short integer Version stamp 

4-7 Long integer Size (in words) of executable code 
8-11 Long integer Size (in words) of initialized data 
12-15 Long integer Size (in bits) of uninitialized data 
16-19 Long integer Entry point 
20-23 Long integer Beginning address of executable code 
24-27 Long integer Beginning address of initialized data 


Section Header Structure 


A.4 Section Header Structure 


COFF object files contain a table of section headers that specify where each 
section begins in the object file. Each section has its own section header. The 
COFFO, COFF1, and COFF2 file types contain different section header infor- 
mation. Table A—4 shows the section header contents for COFFO and COFF1 
files. Table A-5 shows the section header contents for COFF2 files. 


Table A-4. Section Header Contents for COFF 0 and COFF1 Files 


Byte 
Number Type Description 

0-7 Character 8-character section name, padded with nulls 
8-11 Long integer Section’s physical address 
12-15 Long integer Section’s virtual address 
16-19 Long integer Section size in words 
20-23 Long integer File pointer to raw data 
24-27 Long integer File pointer to relocation entries 
28-31 Long integer File pointer to line number entries 
32-33 Unsigned short integer Number of relocation entries 
34-35 Unsigned short integer Number of line number entries 
36-37 Unsigned shortinteger Flags (see Table A—-6) 

38 Character Reserved 

39 Unsigned character Memory page number 


Table A—5. Section Header Contents for COFF2 Files 


Byte Type Description 

0-7 Character 8-character section name, padded with nulls 
8-11 Long integer Section’s physical address 
12-15 Long integer Section’s virtual address 
16-19 Long integer Section size in words 
20-23 Long integer File pointer to raw data 
24-27 Long integer File pointer to relocation entries 
28-31 Long integer File pointer to line-number entries 
32-35 Unsigned long Number of relocation entries 
36-39 Unsigned long Number of line-number entries 
40-43 Unsigned long Flags (see Table A-6) 
44-45 — Short Reserved 
46-47 Unsigned short Memory page number 
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Table A-6 lists the flags that can appear in the section header. 


Table A-6. Section Header Flags 
Mnemonic Flag Description 
STYP_REG 0000h Regular section (allocated, relocated, loaded) 
STYP_DSECT 0001h Dummy section (relocated, not allocated, not loaded) 
STYP_NOLOAD 0002h_ Noload section (allocated, relocated, not loaded) 
STYP_GROUP 0004h_ Grouped section (formed from several input sections) 
STYP_PAD 0008h Padding section (loaded, not allocated, not relocated) 


STYP_COPY 0010h Copy section (relocated, loaded, but not allocated; re- 
location and line-number entries are processed normal- 


ly) 
STYP_TEXT 0020h_ Section that contains executable code 
STYP_DATA 0040h Section that contains initialized data 
STYP_BSS 0080h Section that contains uninitialized data 
STYP_ALIGN 0700h_ Section that is aligned on a page boundary 
Note: The term /oaded means that the raw data for this section appears in the object file. 


The flags listed in Table A-6 can be combined; for example, if the flags word 
is set to 024h, then both STYP_GROUP and STYP_TEXT are set. Bits 8-11 
of the section header flags specify alignment. The alignment is 2". where nis 
the value in bits 8-11. 


The flags are in: 
Bytes For This COFF Format 


36 and 37 COFF1 
40 to 43 COFF2 


Section Header Structure 


Figure A~3 illustrates how the pointers in a section header would point to the 
various elements in an object file that are associated with the .text section. 


Figure A—3. An Example of Section Header Pointers for the .text Section 


text 0-7 811 «12-15 16-19 20-23 24-27 28-31 32-33 34-35 36-37 38 39 


_— 


.text 
raw data 


.text 
relocation information 


.text 
line number entries 


As Figure A—2 on page A-3, shows, uninitialized sections (created with .bss 
and .usect directives) vary from this format. Although uninitialized sections 
have section headers, they have no raw data, relocation information, and line 
number information. They occupy no actual space in the object file. Therefore, 
the number of relocation entries, the number of line number entries, and the 
file pointers are 0 for an uninitialized section. The header of an uninitialized 
section simply tells the linker how much space for variables it should reserve 
in the memory map. 
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A.5 Structuring Relocation Information 


A COFF object file has one relocation entry for each relocatable reference. 
The assembler automatically generates relocation entries. The linker reads 
the relocation entries as it reads each input section and performs relocation. 
The relocation entries determine how references within an input section are 
treated. 


The relocation information entries use the format shown in Table A-7. 


Table A—7. Relocation Entry Contents 


~ Bytes Type Description 

COFF 0: 
0-3 Long integer Virtual address of the reference 
4-5 Unsigned short integer Symbol table index (0Q—65535) 
6-7 Unsigned short integer 16 LSBs of reference, for R_-PARTMS8 
8-9 Unsigned short integer Relocation type (see Table A-8) 

COFF 1 and COFF 2: 
0-3 Long integer Virtual address of the reference 
4-7 Unsigned long integer Symbol table index (0—65535) 
8-9 Unsigned short integer COFF 1: Reserved 


COFF 2: Additional byte used for ex- 
tended address calculations 


10-11 Unsigned short integer Relocation type (see Table A-8) 


The virtual address is the symbol’s address in the current section before re- 
location; it specifies where a relocation must occur. (This is the address of the 
field in the object code that must be patched.) 


Following is an example of code that generates a relocation entry: 


0002 -global xX 
0003 0000 FF80 B X 
0001 0000! 


In this example, the virtual address of the relocatable field is 0001. 


The symbol table index is the index of the referenced symbol. In the 
preceding example, this field would contain the index of X in the symbol table. 
The amount of the relocation is the difference between the symbol’s current 
address in the section and its assembly-time address. The relocatable field 
must be relocated by the same amount as the referenced symbol. In the 
example, X has a value of 0 before relocation. Suppose X is relocated to 
address 2000h. This is the relocation amount (2000h — 0 = 2000h), so the 
relocation field at address 1 is patched by adding 2000h to it. 


Structuring Relocation Information 


You can determine a symbol’s relocated address if you know which section it 
is defined in. For example, if X is defined in .data and .data is relocated by 
2000h, X is relocated by 2000h. 


If the symbol table index in a relocation entry is —1 (OFFFFh), this is called an 
internal relocation. |n this case, the relocation amount is simply the amount by 
which the current section is being relocated. 


The relocation type specifies the size of the field to be patched and describes 
how the patched value should be calculated. The type field depends on the ad- 
dressing mode that was used to generate the relocatable reference. In the pre- 
ceding example, the actual address of the referenced symbol (X) will be placed 
in a 16-bit field in the object code. This is a 16-bit direct relocation, so the re- 
location type is RLRELWORD. Table A-8 lists the relocation types. 


Table A-8. Relocation Types (Bytes 8 and 9) 


“Mnemonic Flag Relocation Type 
R_ABS 0 Absolute address, no relocation 
R_REL24 05 24-bit direct reference to symbol’s address 
R_RELWORD 020 16-bit direct reference to symbol’s address 
R_RELLONG 021 32-bit direct reference to symbol’s address 
R_PCRWORD 023 16-bit PC-relative reference 
R_PCR24 025 24-bit PC-relative reference 
R_PARTLS16 040 16-bit offset of 24-bit address 
R_PARTMS8 041 8-bit page of 24-bit address (16-bit data page 

reference) 
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A.6 Line-Number Table Structure 


The object file contains a table of line number entries that are useful for sym- 
bolic debugging. When the C compiler produces several lines of assembly lan- 
guage code, it creates a line number entry that maps these lines back to the 
original line of C source code that generated them. Each single line number 
entry contains 6 bytes of information. Table A-9 shows the format of a line- 
number entry. 


Table A-9. Line-Number Entry Format 


Byte 
Number Type Description 
0-3 Long integer This entry may have one of two values: 


1) If it is the first entry in a block of line-number entries, 
it points to a symbol entry in the symbol table. 


2) If itis not the first entry in a block, it is the physical ad- 
dress of the line indicated by bytes 4-5. 


4-5 Unsigned This entry may have one of two values: 
shortinteger 4) |f this field is 0, this is the first line of a function entry. 


2) If this field is not 0, this is the line number of a line of 
C source code. 


Figure A-4 shows how line number entries are grouped into blocks. 


Figure A-4. Line-Number Blocks 


Symbol Index 1 0 
physical address line number 


physical address line number 


Symbol Index n 0 


physical address line number 


physical address line number 


As Figure A-4 shows, each entry is divided into halves: 


(1 For the first line of a function, bytes O—3 point to the name of a symbol or 
a function in the symbol table and bytes 4—5 contain a 0, which indicates 
the beginning of a block. 


Line-Number Table Structure 


(J For the remaining lines ina function, bytes 0-3 show the physical address 
(the number of words created by a line of C source) and bytes 4-5 show 
the address of the original C source, relative to its appearance in the C 
source program. 


The line entry table can contain many of these blocks. 


Figure A—5 illustrates the line number entries for a function named XYZ. As 
shown, the function name is entered as a symbol in the symbol table. The first 
portion on XYZ’s block of line number entries points to the function name in the 
symbol table. Assume that the original function in the C source contained three 
lines of code. The first line of code produces 4 words of assembly language 
code, the second line produces 3 words, and the third line produces 10 words. 


Figure A—5. Line-Number Entries Example 
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(Note that the symbol table entry for XYZ has a field that points back to the be- 
ginning of the line number block.) 


Because line numbers are not often needed, the linker provides an option (-s) 
that strips line number information from the object file; this provides a more 
compact object module. 


Common Object File Format A-13 


Symbol Table Structure and Content 


A.7 Symbol Table Structure and Content 


The order of symbols in the symbol table is very important; they appear in the 
sequence shown in Figure A-6. 


Figure A-6. Symbol Table Contents 


filename 1 


function 1 


local symbols 
for function 1 


function 2 


local symbols for 
function 2 


filename 2 


function 1 


local symbols 
for function 1 


static variables 


defined global symbols 
undefined global symbols 


Static variables refer to symbols defined in C that have storage class static out- 
side any function. If you have several modules that use symbols with the same 
name, making them static confines the scope of each symbol to the module 
that defines it (this eliminates multiple-definition conflicts). 


Symbol Table Structure and Content 


The entry for each symbol in the symbol table contains the symbol’s: 


Name (or a pointer into the string table) 

Type 

Value 

Section it was defined in 

Storage class 

Basic type (integer, character, etc.) 

Derived type (array, structure, etc.) 

Dimensions 

Line number of the source code that defined the symbol 


DHOUUUUCUUU 


Section names are also defined in the symbol table. 


All symbol entries, regardless of class and type, have the same format in the 
symbol table. Each symbol table entry contains the 18 bytes of information 
listed in Table A-10. Each symbol may also have an 18-byte auxiliary entry; 
the special symbols listed in Table A-11 on page A-16, always have an auxilia- 
ry entry. Some symbols may not have all the characteristics listed above; if a 
particular field is not set, it is set to null. 


Table A-10. Symbol Table Entry Contents 


Byte 
Number Type Description 
0-7 Character This field contains one of the following: 


1) An 8-character symbol name, padded with nulls 


2) An offset into the string table if the symbol name is 
longer than 8 characters 


8-11 Long integer | Symbol value; storage class dependent 


12-13  Shortinteger Section number of the symbol 


14-15 Unsigned Basic and derived type specification 
short integer 
16 Character Storage class of the symbol 
17 Character Number of auxiliary entries (always 0 or 1) 
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A.7.1 Special Symbols 


The symbol table contains some special symbols that are generated by the 
compiler, assembler, and linker. Each special symbol contains ordinary sym- 
bol table information and an auxiliary entry. Table A—-11 lists these symbols. 


Table A-11. Special Symbols in the Symbol Table 


Symbol Description 

file File name 

.text Address of the .text section 

data Address of the .data section 

.bss Address of the .bss section 

-bb Address of the beginning of a block 

.eb Address of the end of a block 

-bf Address of the beginning of a function 

.ef Address of the end of a function 

.target Pointer to a structure or union that is returned by a function 
.nfake Dummy tag name for a structure, union, or enumeration 

COS End of a structure, union, or enumeration 

etext Next available address after the end of the .text output section 
edata Next available address after the end of the .data output section 
end Next available address after the end of the .bss output section 


Several of these symbols appear in pairs: 
_j .bb/.eb indicate the beginning and end of a block. 


(1 .bf/.ef indicate the beginning and end of a function. 


(1 nfake/.eos name and define the limits of structures, unions, and enumera- 
tions that were not named. The .eos symbol is also paired with named 
structures, unions, and enumerations. 


When a structure, union, or enumeration has no tag name, the compiler as- 
signs ita name so that it can be entered into the symbol table. These names 
are of the form nfake, where nis an integer. The compiler begins numbering 
these symbol names at 0. 


A-16 


Symbol Table Structure and Content 


Symbols and Blocks 


In C, a block is a compound statement that begins and ends with braces. A 
block always contains symbols. The symbol definitions for any particular block 
are grouped together in the symbol table, and are delineated by the .bb/.eb 
special symbols. Blocks can be nested in C, and their symbol table entries can 
be nested correspondingly. Figure A-7 shows how block symbols are grouped 
in the symbol table. 


Figure A—7. Symbols for Blocks 
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Symbols and Functions 


The symbol definitions for a function appear in the symbol table as a group, 
delineated by .bf/.ef special symbols. The symbol table entry for the function 
name precedes the .bf special symbol. Figure A-8 shows the format of symbol 
table entries for a function. 


Figure A—8. Symbols for Functions 


Symbols for 
the function 


If a function returns a structure or union, then a symbol table entry for the spe- 
cial symbol .target will appear between the entries for the function name and 
the .bf special symbol. 
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A.7.2 Symbol Name Format 


The first 8 bytes of a symbol table entry (bytes 0—7) indicate a symbol’s name: 


(1 If the symbol name is 8 characters or less, this field has type character. 
The name is padded with nulls (if necessary) and stored in bytes 0-7. 


_j Ifthe symbol name is greater than 8 characters, this field is treated as two 
long integers. The entire symbol name is stored in the string table. Bytes 
0-3 contain 0, and bytes 4—7 are an offset into the string table. 


A.7.3 String Table Structure 


Symbol names that are longer than eight characters are stored in the string 
table. The field in the symbol table entry that would normally contain the sym- 
bol’s name contains, instead, a pointer to the symbol’s name in the string table. 
Names are stored contiguously in the string table, delimited by a null byte. The 
first four bytes of the string table contain the size of the string table in bytes; 
thus, offsets into the string table are greater than or equal to four. 


Figure A-9 is a string table that contains two symbol names, Adaptive—Filter 
and Fourier—Transform. The index in the string table is 4 for Adaptive—Filter 
and 20 for Fourier—Transform. 


Figure A-9. Sample String Table 
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A.7.4 Storage Classes 


Byte 16 of the symbol table entry indicates the storage class of the symbol. 
Storage classes refer to the method in which the C compiler accesses a sym- 
bol. Table A—-12 lists valid storage classes. 


Table A-12. Symbol Storage Classes 

Mnemonic Value Storage Class Mnemonic Value Storage Class 

C_NULL 0 No storage class C_USTATIC 14 — Uninitialized static 

C_AUTO 1 Automatic variable C_ENTAG 15 Enumeration tag 

C_EXT 2 External symbol C_MOE 16 Member of an enumeration 

C_STAT 3 Static C_REGPARM 17 —- Register parameter 

C_REG 4 Register variable C_FIELD 18 Bit field 

C_EXTDEF 5 External definition C_UEXT 19 Tentative definition 

C_LABEL 6 Label C_STATLAB 20 Static .label symbol 

C_ULABEL 7 Undefined label C_EXTLAB 21 External .label symbol 

C_MOS 8 Member of a structure C_BLOCK 100 Beginning or end of a block; 
used only for the .ob and .eb 
special symbols 

C_ARG 9 Function argument C_FCN 101. = Beginning or end of a func- 
tion; used only for the .bf and 
.ef special symbols 

C_STRTAG 10 Structure tag C_EOS 102 ~~ End of structure; used only 
for the .eos special symbol 

C_MOU 11 Member of a union C_FILE 103 Filename; used only for the 
file special symbol 

C_UNTAG 12 Union tag C_LINE 104 Usedonly by utility programs 

C_TPDEF 13 Type definition 


Some special symbols are restricted to certain storage classes. Table A-13 
lists these symbols and their storage classes. 
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Table A-13. Special Symbols and Their Storage Classes 


Special Restricted to This Special ~ Restricted to This 
Symbol Storage Class Symbol Storage Class 

file C_FILE .e0S C_EOS 

.bb C_BLOCK text C_STAT 

.eb C_BLOCK .data C_STAT 

bf C_FCN .bss C_STAT 

.ef C_FCN 


A.7.5 Symbol Values 


Bytes 8-11 of asymbol table entry indicate a symbol’s value. A symbol’s value 
depends on the symbol’s storage class; Table A-14 summarizes the storage 
classes and related values. 


Table A-14._ Symbol Values and Storage Classes 


Storage Class Value Description Storage Class “Value Description _ 
C_AUTO Stack offset in bits C_UNTAG 0 

C_EXT Relocatable address_ || C_TPDEF 0 

C_UEXT 0 C_NULL none 

C_EXTDEF Relocatable address |} C_USTATIC 0 

C_STAT Relocatable address |] C_ ENTAG 0 

C_REG Register number C_MOE Enumeration value 
C_LABEL Relocatable address |!C REGPARM _ Register number 
C_ULABLE Relocatable address _ || C_STATLAB Relocatable address 
C_MOS Offset in bits C_FIELD Bit displacement 
C_ARG Stack offset in bits C_BLOCK Relocatable address 
C_STRTAG 0 C_FCN Relocatable address 
C_EOS 0 C_LINE 0 

C_MOU Offset in bits C_FILE 0 

C_EXTLAB Relocatable address 


If asymbol’s storage class is C_FILE, the symbol’s value is a pointer to the next 
file symbol. Thus, the .file symbols form a one-way linked list in the symbol 
table. When there are no more .file symbols, the final .file symbol points back 
to the first .file symbol in the symbol table. 


Symbol Table Structure and Content 


The value of a relocatable symbol is its virtual address. When the linker relo- 
cates a section, the value of a relocatable symbol changes accordingly. 


A.7.6 Section Number 


Bytes 12-13 of asymbol table entry contain anumber that indicates which sec- 
tion the symbol was defined in. Table A-15 lists these numbers and the sec- 


tions they indicate. 


Table A-15. Section Numbers 


Section 
Mnemonic Number 
N_ DEBUG -2 
N_ABS -1 
N_UNDEF 0 
N_SCNUM 1 
N_SCNUM 2 
N_SCNUM 3 
N_SCNUM 4-32,767 


Description 

Special symbolic debugging symbol 
Absolute symbol 

Undefined external symbol 

.text section (typical) 

.data section (typical) 

-bss section (typical) 


Section number of a named section, in the order in 
which the named sections are encountered 


If there were no .text, .data, or .bss sections, the numbering of named sections 


would begin with 1. 


Ifa symbol has a section number of 0, —1, or —2, then it is not defined in a sec- 
tion. A section number of —2 indicates a symbolic debugging symbol, which 
includes structure, union, and enumeration tag names; type definitions; and 
filenames. A section number of —1 indicates that the symbol has a value but 
is not relocatable. A section number of 0 indicates a relocatable external sym- 
bol that is not defined in the current file. 


A.7.7 Type Entry 


Bytes 14—15 of the symbol table entry define the symbol’s type. Each symbol 
has one basic type and one to six derived types. 


Following is the format for this 16-bit type entry: 


Derived | Derived | Derived | Derived Derived | Derived Basi 
Type Type Type Type Type Type eine 
; 6 5 4 3 2 { ype 
Size 
(in bits): 2 2 2 2 2 2 4 
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Bits 0-3 of the type field indicate the basic type. Table A—-16 lists valid basic 
types. 


Table A-16. Basic Types 


Mnemonic Value Type 

T_NULL 0 Type not assigned 
T_CHAR 2 Character 

T_SHORT 3 Short integer 

T_INT 4 Integer 

T_LONG 5 Long integer 
T_FLOAT 6 Floating point 
T_DOUBLE 7 Double word 
T_STRUCT 8 Structure 

T_UNION 9 Union 

T_ENUM 10 Enumeration 

T_MOE 11 Member of an enumeration 
T_UCHAR 12 Unsigned character 
T_USHORT 13 Unsigned short integer 


Bits 4-15 of the type field are arranged as six 2-bit fields, which can indicate 
1 to 6 derived types. Table A—17 lists the possible derived types. 


Table A-17. Derived Types 


Mnemonic Value Type 

DT_NON 0 No derived type 
DT_PTR 1 Pointer 
DT_FCN 2 Function 
DT_ARY 3 Array 


An example of a symbol with several derived types would be a symbol with a 
type entry of 00000000110100115. This entry indicates that the symbol is a 
pointer to an array of short integers. 
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A.7.8 Auxiliary Entries 


Each symbol table entry may have one or no auxiliary entry. An auxiliary sym- 
bol table entry contains the same number of bytes as a symbol table entry (18), 
but the format of an auxiliary entry depends on the symbol’s type and storage 
class. Table A-18 summarizes these relationships. 


Table A-18. Auxiliary Symbol Table Entries Format 


Type Entry 

Storage ————————— 13 

Name Class Derived Basic Auxiliary Entry Format 
Type 1 Type 

file C_FILE DT_NON T_NULL Filename (see Table A-19) 
.text, .data, .bss C_STAT DT_NON T NULL Section (see Table A—20) 
tagname C_STRTAG DT_NON T_NULL Tag name (see Table A—21) 

C_UNTAG 

C_ENTAG 
.e0S C_EOS DT_NON T NULL End of structure (see Table A—22) 
fcname C_EXT DT_FCN (See note 1) Function (see Table A—23) 

C_STAT 
arrname (See note 2) DT_ARY (See note 1) Array (see Table A—24) 
-bb, .eb C_BLOCK DT_NON T_NULL Beginning and end of a block (see 

Table A—25 and Table A—26) 
-bf, .ef C_FCN DT_NON T_ NULL Beginning and end of a function (see 
Table A—25 and Table A—26) 

Name relatedtoa (See note 2) DT_PTR T_STRUCT Name related to a structure, union, 
structure, union, or DT_ARR T_UNION or enumeration (see Table A—27) 
enumeration 


DT_NON T_ENUM 


Notes: 1) Any except T.MOE 


2) 


C_AUTO, C_STAT, C_MOS, C_MOU, C_TPDEF 


In Table A-18, tagname refers to any symbol name (including the special sym- 
bol nfake). Fename and arrname refer to any symbol name. 


A symbol that satisfies more than one condition in Table A-18 should have a 
union format in its auxiliary entry. A symbol that satisfies none of these condi- 
tions should not have an auxiliary entry. 
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Filenames 


Each of the auxiliary table entries for a filename contains a 14-character file 
name in bytes 0-13. Bytes 14-17 are not used. 


Table A-19. Filename Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-13 Character File name 


14-17 — Unused 


Sections 


Table A—20 illustrates the format of the auxiliary table entries. 


Table A-20. Section Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-3 Long integer Section length 
4-6 Unsigned short integer Number of relocation entries 
7-8 Unsigned short integer Number of line number entries 


9-17 — Unused (zero filled) 


Tag Names 


Table A—21 illustrates the format of auxiliary table entries for tag names. 


Table A-21. Tag Name Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-5 —_— Unused (zero filled) 
6-7 Unsigned short integer Size of structure, union, or enumeration 
8-11 _— Unused (zero filled) 
12-15 Long integer Index of next entry beyond this structure, 
union, or enumeration 
16-17 —_— Unused (zero filled) 


End of Structure 
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Table A—22 illustrates the format of auxiliary table entries for ends of struc- 


tures. 


Table A-22. End-of-Structure Format for Auxiliary Table Entries 


Byte 
Number 


0-3 
4-5 
6-7 
8-17 


Functions 


Type 


Long integer 


Unsigned short integer 


Description 

Tag index 

Unused (zero filled) 

Size of structure, union, or enumeration 


Unused (zero filled) 


Table A—23 illustrates the format of auxiliary table entries for functions. 


Table A—23. Function Format for Auxiliary Table Entries 


Byte 
Number 


0-3 

4-7 
8-11 
12-15 
16-17 


Type 
Long integer 


Long integer 
Long integer 
Long integer 


Description 

Tag index 

Size of function (in bits) 

File pointer to line number 

Index of next entry beyond this function 


Unused (zero filled) 
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Arrays 


Table A—24 illustrates the format of auxiliary table entries for arrays. 


Table A—24. Array Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-3 Long integer Tag index 
4-5 Unsigned short integer Line number declaration 
6-7 Unsigned short integer Size of array 
8-9 Unsigned short integer First dimension 
10-11 Unsigned short integer Second dimension 
12-13 Unsigned short integer Third dimension 
14-15 Unsigned short integer Fourth dimension 
16-17 _— Unused (zero filled) 


End of Blocks and Functions 


Table A—25 illustrates the format of auxiliary table entries for the ends of blocks 
and functions. 


Table A-25. End-of-Blocks and Functions Format for Auxiliary Table Entries 


Byte 

Number Type Description 
0-3 _— Unused (zero filled) 
4-5 Unsigned short integer C source line number 
6-17 — Unused (zero filled) 
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Beginning of Blocks and Functions 


Table A—26 illustrates the format of auxiliary table entries for the beginnings 
of blocks and functions. 


Table A-26. Beginning-of-Blocks and Functions Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-3 — Unused (zero filled) 
4-5 Unsigned short integer C source line number of block begin 
6-11 — Unused (zero filled) 
12-15 Long integer Index of next entry past this block 
16-17 —_— Unused (zero filled) 


Names Related to Structures, Unions, and Enumerations 


Table A—27 illustrates the format of auxiliary table entries for the names of 
structures, unions, and enumerations. 


Table A-27. Structure, Union, and Enumeration Names Format for Auxiliary Table Entries 


Byte 
Number Type Description 
0-3 Long integer Tag index 
4-5 —_— Unused (zero filled) 
6-7 Unsigned short integer Size of the structure, union, or enumeration 
8-17 —_— Unused (zero filled) 
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Symbolic Debugging Directives 


The TMS320C3x/C4x assembler supports several directives that the 
TMS320C3x/C4x C compiler uses for symbolic debugging: 


Lj) The.sym directive defines a global variable, a local variable, or a function. 
Several parameters allow you to associate various debugging information 
with the symbol or function. 


L) The .stag, .etag, and .utag directives define structures, enumerations, 
and unions, respectively. The .member directive specifies a member of a 
structure, enumeration, or union. The .eos directive ends a structure, enu- 
meration, or union definition. 


_) The .func and .endfunc directives specify the bounds of C blocks. 
_} The .block and .endblock directives specify the bounds of C blocks. 


_j The .file directive defines a symbol in the symbol table that identifies the 
current source file name. 


_} The .line directive identifies the line number of a C source statement. 


These symbolic debugging directives are not usually listed in the assembly 
language file that the compiler creates. If you want them to be listed, invoke 
the compiler with the -g option, as shown below: 


c130 -g <input file> 


This appendix contains an alphabetical directory of the symbolic debugging 
directives. Each directive contains an example of C source and the resulting 
assembly language code. 
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Define a Block 


Syntax 


Description 


Example 


-block beginning line number 
-endblock ending line number 


The .block and .endblock directives specify the beginning and end of a C block. 
The line numbers are optional; they specify the location in the source file where 
the block is defined. 


Note that block definitions can be nested. The assembler will detect improper 
block nesting. 


Here is an example of C source that defines a block, and the resulting 
assembly language code. 


C source: 
{ /* Beginning of a block */ 
int a,b; 
a=b; 
} /* End of a block */ 


Resulting assembly language code: 


-block 12 
.sym aly 644 94-32 
.sym _b,7,4,1,32 
-line 13 


LDI *+FP(2), RO 
STI RO, *+FP (1) 
-endblock 14 


Syntax 


Description 


Example 


Supply a File Identifier 


file “filename” 


The .file directive allows a debugger to map locations in memory back to lines 
inaC source file. The filename is the name of the file that contains the original 
C source program. The first 14 characters of the filename are significant. 


You can also use the .file directive in assembly code to provide a name in the 
file and improve program readability. 


Here is an example of the .file directive. The filename named fext.c contained 
the C source that produced this directive. 


. file "text.c” 
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Define a Function 


Syntax 


Description 


Example 


lune beginning line number 


-endfune ending line number [, save on entry mask, 
local frame size] 


The .func and .endfunc directives specify the beginning and end of a C func- 
tion. The parameters are optional; the line numbers specify the location in the 
source file where the function is defined. The save—on—entry mask and local 
frame size are generated by the compiler. The save—on—entry mask is used 
to identify (for debugging purposes) the registers that have been pushed on 
the stack at the start of this function. The local frame size value, if given, is also 
used by the debugger to locate auto variables, and the value listed in this direc- 
tive equals the amount of space set aside on the stack for local variables of 
the corresponding function. 


Note that function definitions cannot be nested. 


Here is an example of C source that defines a function, and the resulting 
assembly language code. 


C source: 


addl (int x) 


{ 
int y; 


y= x1; 
return y; 


a 
AIAN BWNHE 


oOo w 
Nr wo 


anu 
Noe 


00000000 


00000000 
00000001 
00000002 


00000003 
00000004 
00000005 


00000006 
00000007 
00000008 
00000009 


r 


Define a Function 


Resulting assembly language code: 


* FUNCTION NAME 


Architecture 


Calling Convention: 


Function Uses 


Stack Frame 


-global _addl 
.sym _addi1,_add1,36,2,0 
. func al 
ERS REKK RAKE ARKH EEKER ERE REKER ERE EEK ER EKE EEK EREKE KEK ERE KE HK 
: _addl 7 
* 
:TMS320C30 * 
Stack Parameter Convention x 
Regs: r0 bat 
. * 
Full (w/ debug) * 


’ 


Total Frame Size 


* 
* 
* 
* Regs Saved 
* 
* 
* 


1 Parm + 1 Auto + 0 SOE = 3 bytes* 


KKK KKK KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KKK KK KKK KK 


_addl: 


0£2b0000 
500b0014 
02740001 


50600001 
02400B02 
15400301 


50410b01 
504bc300 
50440003 
68000001 


.line 
PUSH 
LDIU 
ADDI 

.sym 

.sym 

.line 

.line 
LDIU 
ADDI 
STI 

.line 

.line 
LDIU 
LDIU 
SUBI 
BU 

-endfunc 


FP 
SP,FP 
1, SP 
_x,-1,4, 9,32 
_y,1,4,1,32 
2 
5 
1,R0 
*—-FP (2),RO 
RO, *+FP (1) 
6 
7 
*-FP(1),R1 
*FP,FP 
3,SP 
R1 


7,000000000H, 0 
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Create a Line Number Entry 


Syntax 


Description 


Example 


B-6 


line /ine number [, address] 


The .line directive creates a line number entry in the object file. Line number 
entries are used in symbolic debugging to associate addresses in the object 
code with the lines in the source code that generated them. 


The .line directive has two operands: 


(j) Line number indicates the line of the C source that generated a portion of 
code. Line numbers are relative to the beginning of the current function. 
This is a required parameter. 


(1 Address is an expression that is the address associated with the line 
number. This is an optional parameter; if you don’t specify an address, the 
assembler will use the current SPC value. 


The .line directive is followed by the assembly language source statements 
that are generated by the indicated line of C source. For example, assume that 
the lines of C source below are lines 4 and 5 in the original C source; these lines 
may produce the assembly language statements shown below. 


C source: 
for (i = 1; i <= n; ++i) 
p=p* x; 


Resulting assembly language code: 


64 -line 4 

68 0000000c 50600001 ldiu 1,RO 

69 0000000d 15400301 sti RO, *+f£p (1) 
70 0000000e 04c00304 cmpi *+fp(4),R0 
71 OOO00000F 6a090009 bgt L3 

73 00000010 L2: 

74 -line 5 

78 00000010 50400305 ldiu *+fp(5),RO0 
79 0000011 50410306 ldiu *+fp(6),R1 
80 00000012 62000000! call MPY_130 

82 00000013 15400305 sti RO, *+fp (5) 
83 -line 4 

84 00000014 50600001 ldiu 1,RO 

85 00000015 02400301 addi *+fp(1),R0 
86 00000016 15400301 sti RO, *+fp (1) 
87 00000017 04c00304 cmpi *+fp(4),R0 
88 00000018 6a08fff7 ble L2 

90 00000019 L3: 

91 .-line 6 


Syntax 


Description 


Example 


Define a Member 


-member name, value [, type, storage class, size, tag, dims] 


The .member directive defines a member of a structure, union, or 
enumeration. It is valid only when it appears in a structure, union, or 
enumeration definition. 


LJ 


LJ 


Lj 


Name is the name of the member that is put in the symbol table. The first 
32 characters of the name are significant. 


Value is the value associated with the member. Any legal expression (ab- 
solute or relocatable) is acceptable. 


Type is the C type of the member. Appendix A contains more information 
about C types. 


Storage class is the C storage class of the member. Appendix A contains 
more information about C storage classes. 


Size is the number of bits of memory required to contain this member. 


Tag is the name of the type (if any) or structure of which this member is a 
type. This name must have been previously declared by a .stag, .etag, or 
.utag directive. 


Dims may be one to four expressions separated by commas. This allows 
up to four dimensions to be specified for the member. 


The order of parameters is significant. Name and value are required 
parameters. All other parameters may be omitted or empty (adjacent commas 
indicate an empty entry). This allows you to skip a parameter and specify a pa- 
rameter that occurs later in the list. Operands that are omitted or empty as- 
sume a null value. 


Here is an example of aC structure definition and the corresponding assembly 
language statements: 


C source: 


struct doc { 


char title; 
char group; 
int job_number; 


} doc_info; 


Resulting assembly language code: 


.stag doc, 48 

-member _title,0,2,8,8 
-member J_group, 8,2, 8,8 
-member _vJob_number,16, 4, 8, 32 
-e0s 
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Define a Structure 


Syntax 


Description 


Example 1 


stag name |, size] 
member definitions 

.e€OS 

.etag name |, size] 
member definitions 

.eOS 

-utag name [, size] 
member definitions 

.e€OS 


The .stag directive begins a structure definition. The .etag directive begins an 
enumeration definition. The .utag directive begins a union definition. The .eos 
directive ends a structure, enumeration, or union definition. 


_j} Name is the name of the structure, enumeration, or union. The first 32 
characters of the name are significant. This is a required parameter. 


1 Size is the number of bits the structure, enumeration, or union occupies 
in memory. This is an optional parameter; if omitted, the size is 
unspecified. 


The .stag, .etag, or .utag directive should be followed by a number of .member 
directives, which define members in the structure. The .member directive is 
the only directive that can appear inside a structure, enumeration, or union 
definition. 


The assembler does not allow nested structures, enumerations, or unions. 
The C compiler unwinds nested structures by defining them separately and 
then referencing them from the structure they are referenced in. 


Here is an example of a structure definition. 


C source: 


struct doc 
{ 

char title; 

char group; 

int job_number; 
} doc_info; 


Resulting assembly language code: 


.stag _doc, 96 

-member _title,0,2,8,32 
-member _group, 32,2, 8,32 
-member _job_number, 64, 4, 8, 32 
.e0s 


Example 2 


Example 3 


Define a Structure 


Here is an example of a union definition. 


C source: 


union u_tag { 
int vall; 
float val2; 
char valc; 
}) valu; 


Resulting assembly language code: 


-utag _u_tag, 96 
-member _vall1,0,2,8,32 
-member _val2,32,4,8,32 
-member _valc, 64,4,8, 32 
.e€0s 


Here is an example of an enumeration definition. 


C Source: 


{ 
enum o_ty { reg_l, reg_2, result } optypes; 


} 
Resulting assembly language code: 


.etag _o_ty32 

-member _reg_1,10,11,16,32 
-member _reg_2,1,11,16, 32 
-member _result,2,11,16,32 
.eos 
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Define a Symbol 


Syntax 


Description 


Example 


B-10 


sym name, value [, type, storage class, size, tag, dims] 


The .sym directive specifies symbolic debug information about a global vari- 
able, local variable, or a function. 


1 Nameis the name of the variable that is put in the object symbol table. The 
first 32 characters of the name are significant. 


(j Value is the value associated with the variable. Any legal expression 
(absolute or relocatable) is acceptable. 


1 Type is the C type of the variable. Appendix A contains more information 
about C types. 


(4 Storage class is the C storage class of the variable. Appendix A contains 
more information about C storage classes. 


(j Size is the number of bits of memory required to contain this variable. 


1 Tag is the name of the type (if any) or structure of which this variable is a 
type. This name must have been previously declared by a .stag, .etag, or 
.utag directive. 


(J) Dims may be up to four expressions separated by commas. This allows 
up to four dimensions to be specified for the variable. 


The order of parameters is significant. Name and value are required parame- 
ters. All other parameters may be omitted or empty (adjacent commas indicate 
an empty entry). This allows you to skip a parameter and specify a parameter 
that occurs later in the list. Operands that are omitted or empty assume a null 
value. 


These lines of C source produce the .sym directives shown below: 


C source: 


struct s { int memberl, member2; } str; 
int ext; 

int array[5][10]; 

long *ptr; 

STE: strcmp (); 


main(argl,arg2) 
int argl; 


char *arg2; 


register rl; 


Define a Symbol 


Resulting assembly language code: 


.sym _str,_str,8,2,64,_s 

.sym _ext,_ext,4,2,32 

.sym _array,_array,244,2,1600,,5,10 
.sym aptr, ptr, 21,27,.32 

.sym _main,_main, 36,2,0 

.sym _argl,_argl,-2,4,9,32 

.sym _arg2,_arg2,-3,18, 9,32 

.sym a1, 4,4,4,32 
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Assembler Error Messages 


The assembler issues several types of error messages: 


_j Fatal 
_) Nonfatal 
_j) Macro 


When the assembler completes its second pass, it reports any errors that it 
encountered during the assembly. It also prints these errors in the listing file 
(if one is created). An error is printed following the source line that incurred it. 


This appendix discusses the three types of assembler error messages. They 
are listed in alphabetical order. Most errors are fatal; if an error is not fatal or 
if it is a macro error, this is noted in the list. Most error messages have a 
description of the problem and an action that suggests possible remedies. 
Where the error message itself is an adequate description, you may find only 
the action suggested. Where the action is obvious from the description 
(inspect and correct code), the action is omitted. 


absolute value required 


Description A relocatable symbol was used where an absolute symbol 
was expected. 


Action Use an absolute symbol. 


a component of the expression is invalid 


Description Something other than a constant identifier or operator was 
used in the expression. 


Action Identify and eliminate the offending component. 
address register required: SP, DP, IRX, or ARX 


Description The operand of the LDA instruction must be one of these reg- 
isters. 


C-1 


Assembler Error Messages 


address required 
Description This instruction requires an address as an operand. 


an identifier in the expression is invalid 


Description A character-matching function requires a character constant 
operand. 


Action Use a character constant. 


argument must be character constant 
Description A character-matching function requires a character constant 
Action Use a character constant. 


auxiliary register required for indirect 
Description This instruction requires an auxiliary register as an operand. 


bad macro library format 
Description The macro library specified was not in the format expected. 


Action Macro libraries must be unassembled assembler source files. 
The macro name and member name must be the same, and 
the extension of the file must be .asm. 


blank missing 


Description A blank or blanks must separate each field of the source 
statement. 


-break encountered outside loop block 
Description The .break directive is valid only inside a loop block. 


Action Examine code for a misplaced .endloop directive or remove 
the .break directive. 


cannot equate an external to an external 


Description Both of the operands of this .set directive are used with .global 
directives. 


Action One and only one of the operands may be .global. 
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cannot open library 


Description Alibrary name specified with the .mlib directive does not exist 
or is already being used. 


Action Check spelling, pathname, environment variables, etc. 


cannot open listing file : filename 
Description The specified filename is inaccessible for some reason. 


Action Check spelling, pathname, environment variables, etc. 


cannot open object file : filename 
Description The specified filename is inaccessible for some reason. 


Action Check spelling, pathname, environment variables, etc. 


cannot open source file : filename 
Description The specified filename is inaccessible for some reason. 


Action Check spelling, pathname, environment variables, etc. 


cannot redefine register 
Description An attempt was made to redefine a register name. 


Action Register names cannot be used as labels. 


character constant overflows a word 
Description Character constants should be limited to four characters. 


close ()) missing 
Description Mismatched parentheses. 


close (]) missing 


Description Mismatched brackets. 


close quote missing 
Description Mismatched or missing quotes. 


Action All strings must be enclosed in quotes. 
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comma missing 
Description The assembler expected a comma but did not find one. 


Action In most cases, the instruction requires more operands than 
were found. 


conditional block nesting level exceeded 
Description Conditional block nesting cannot exceed 32 levels. 


conflicts with previous section definition 


Description A section defined with .sect or .usect cannot be redefined 
with the other directive. 


Action Change the directives to match or rename one of the 
sections. 


copy file open error 


Description A file specified by a .copy directive does not exist or is already 
being used. 


Action Check spelling, pathname, environment variables, etc. 


directive only valid if (-a) option used 


Description The .setsect and .setsym directives can be used only if the —a 
(absolute list) option is specified. 


Action Remove statements or invoke assembler with —a. 


divide by zero 


Description An expression or well-defined expression contains invalid 
division. 


duplicate definition 


Description The symbol appears as an operand of a REF statement, as 
well as in the the label field of the source, or the symbol 
appears more than once in the label field of the source. 


Action Examine code for above. Use .newblock to reuse local labels. 
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duplicate definition of a structure component 


Description A structure tag, member, or size symbol was defined 
elsewhere or used in a .global directive. 


.else or .elseif needs corresponding .if 


Description An .else or .elseif directive was not preceded by an .if 
directive. 


empty structure 


Description A .struct/.endstruct sequence must have at least one 
member. 


expansion register required 
Description This instruction requires a ’C4x expansion file register. 


expression changed values due to branch expansion 


Description An expression is dependent on the amount of code between 
two labels. If the assembler expands a branch in the code 
between these two labels, this expression will evaluate to 
different values in pass1 and pass2. 


Action Manually expand any branches between the two labels in 
your source code that were automatically expanded by the 
assembler. 


expression not terminated properly 


Description Expressions must be delimited by commas, parentheses, or 
blanks. 


expression out of bounds 


Description The value specified is too large for this particular instruction or 
directive. 


extended register RO-R7 required 
Description Parallel instructions operate only on these registers. 
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filename missing 
Description The specified filename cannot be found. 


Action Check spelling, pathname, environment variables, etc. 


floating-point number not valid in expression 


Description A floating-point expression was used where an integer 
expression is required. 


garbage on command line 
Description The specified options are illegal or unrecognized. 


illegal label 


Description A label cannot be used for the second instruction of a parallel 
instruction pair. 


illegal operation in expression 


Description This message is usually generated by an illegal combination 
of relocatable or external operands. 


Action Consult Table 3-2 on page 3-23. 


illegal structure definition 


Description The .stag/.eos structure definition cannot be nested and 
cannot contain any debugging directives other than member. 


illegal structure member 


Description Only directives that reserve space are allowed in structure 
definitions. 


Action Consult Directives that Initialize Constants in beginning on 
page 4-7. 
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illegal structure, union, or enumeration tag 


Description The operands of .stag must be identifiers. 


illegal use of local label 


Description Local labels are not allowed in expressions. 


incompatible addressing modes 


Description Although each operand is correctly formed, the combination 
is not valid for this instruction. 


index register required for displacement 


Description Indirect displacement must be a constant, IRO, or IR1. 


indirect address required 


Description This instruction expects an indirect address as an operand. 


indirect displacement must be 0 or 1 


Description This message applies to several 3-operand and parallel 
instructions. 


indirect displacement out of bounds 
Description Range must be 0-255. 


invalid binary constant 


Description The only valid binary integers are 0 and 1; the constant must 
be suffixed with b or B. 


invalid bit-reversed modification 


Description Bit-reversed modification is legal only with *AR++(IRO) 
addressing mode. 


invalid branch displacement 


Description PC relative branch destination is too far away. 
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invalid circular modification 


Description Circular modification legal with *~AR++(disp), “AR—(disp), 
*AR++(IR), or *AR—(IR) only. 


invalid decimal constant 
Description The only valid decimal integers are 0-9. 


Action This error is most commonly caused by failure to use hor Has 
the postfix on a hexadecimal number. 


invalid expression 


Description This may indicate invalid use of a relocatable symbol in 
arithmetic. 


invalid floating-point constant 


Description Either the floating-point constant is incorrectly formed, or an 
integer constant is used where a floating-point constant is 
required. 


invalid hexadecimal constant 


Description The only valid hexadecimal digits are the integers are 0-9 and 
the letters A-F. The constant must be suffixed with h or H, and 
it must begin with an integer. 


invalid octal constant 


Description The only valid octal digits are the integers are 0-8; the 
constant must be suffixed with gq or Q. 


invalid opcode 


Description The command field of the source record has an entry that is 
not a defined instruction, directive, or macro name. 


invalid opcode for selected version 


Description An illegal instruction is used for selected CPU. Check the —v 
option or .version directive. 
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invalid operand combination—check version 


Description An illegal instruction is used for selected CPU. Check the —v 
option or .version directive. 


invalid option 


Description An option specified by the .option directive is invalid. 


invalid parallel instruction combination 


Description These two instructions cannot be combined as one parallel 
instruction. Only certain combinations are legal. 


invalid symbol qualifier 


Description A symbol name is a string of up to 32 alphanumeric 
characters (A-Z (either case), 0-9, $, and _) and cannot 
begin with a number. 


label required 


Description The flagged directive must have a label. 


library not in archive format 
Description A file specified with an .mlib directive is not an archive file. 


Action Macro libraries must be unassembled assembler source files. 
The macro name and member name must be the same, and 
the extension of the file must be .asm. 


local label multiply defined in block 


Description Local labels cannot be defined more than once in the current 
block. 


Action Use the .newblock directive to reuse local labels in the same 
block. 
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local label not defined in block 


Description A local label is used outside the block that it is defined in, or it 
is not defined at all. 


local macro variable is not a valid symbol 
Description The operand of .var must be a valid symbol. 


Action Consult subsection 6.3.7 on page 6-12. 


macro parameter is not a valid symbol 
Description The macro parameter must be a valid identifier. 


Action Section 6.3, beginning on page 6-5, discusses macro 
parameters. 


maximum macro nesting level exceeded 


Description The maximum nesting level is 32. 


maximum number of copy files exceeded 


Description The maximum nesting level for .copy or .include files is 10. 


.mexit directive encountered outside macro 


Description The .mexit directive is valid only inside macros. 


missing .endif directive 


Description An .if directive has no matching .endif. 


missing .endloop directive 


Description A .loop directive has no matching .endloop. 


missing .endm directive 


Description A .macro directive has no matching .endmacro directive. 
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missing first half of parallel instruction 


Description The || symbol was used on the first statement in a section or 
the first instruction was badly formed. 


missing macro name 


Description The .macro directive requires a name. 


missing structure tag 


Description The .tag directive requires a symbol name. 


no include/copy files in macro or loop blocks 


Description .include and .copy directives are not allowed inside macros 
(.macro/.endm) or loop blocks (.loop/.break/.endloop). 


no parameters for macro arguments 


Description A macro was called with arguments, but no matching 
parameters were found in the macro definition. 


open “(“ expected 


Description A built-in function was used improperly, or mismatched 
parentheses were found. 


operand missing 


Action An operand must be supplied. 


operand must be an immediate value 


Description The operand for this instruction must be an immediate value. 
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operand must be register or indirect 


Description For 3-operand or parallel instructions. 


out of memory, aborting 
Description The assembler has run out of memory and cannot continue. 


Action Break the assembly language file into smaller files that can be 
assembled at one time. 


overflow in floating-point constant 


Description Floating-point value too large to be represented. 


pass1/pass2 operand conflict 


Description A symbol in the symbol table did not have the same value in 
pass1 and pass2. 


Action This is an internal assembler error. If it occurs repeatedly, the 
assembler may be corrupt. 


positive value required 


Description Negative or zero value not allowed. 


redefinition of local substitution symbol 


Description Local substitution symbols can be defined only once in a 
macro. 


register required 


Description This instruction requires a register as an operand. 
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string required 
Description You must supply a string that is enclosed in double quotes. 


string table larger than PC segment size 
Description The maximum size for a string table is 64 K bytes. 


substitution symbol stack overflow 
Description Maximum number of nested substitution symbols is 10. 


substitution symbol string too long 
Description Maximum substitution symbol length is 200 characters. 


subtraction of labels not allowed 


Description Subtraction of labels or relationals involving the amount of 
code between labels is not allowed in expressions used in 
some contexts. 


Action Refer to Table 3—2 on page 3-23. 


symbol required 
Description The .global directive requires a symbol as an operand. 


symbol used in both REF and DEF 
Description A REFed symbol is already defined. 


syntax error 
Description An expression is improperly formed. 


too many local substitution symbols 


Description The maximum number of local substitution symbols is ~ 
64,000. 
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unable to open temp macro library filename 


Description The assembler uses a temporary file for holding macro 
definitions. It was unable to create/open this file. 


Action Check disk space and protection. 


unbalanced symbol table entries 


Description Incorrectly scoped .block and .func directives. 


undefined structure member 


Description A symbol referenced with structure reference notation (a.b) is 
not declared in a .struct/.endstruct sequence. 


undefined structure tag 


Description The operand of .tag must be defined with a .struct directive. 


undefined substitution symbol 


Description The operand of a substitution symbol must be defined either 
as a macro parameter or with a .asg or .eval directive. 


undefined symbol 


Description An undefined symbol was used where a well-defined 
expression is required. 


underflow in floating-point constant 


Description Floating-point value is too small to represent. 


unexpected .endif encountered 


Description An .endif directive was not preceded by a .loop directive. 


unexpected .endloop encountered 


Description An .endloop directive was not preceded by a .loop directive. 
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unexpected .endm directive encountered 


Description An .endm directive was not preceded by a .macro directive. 


unexpected .endstruct directive encountered 


Description An .endstruct directive was not preceded by a -struct 
directive. 


unknown model option [—m_], ignored 


Description Unrecognized —m option. 


**USER ERROR** 


Description Output from an .emsg directive. 


**USER MESSAGE** 


Description Output from a .mmsg directive. 


**USER WARNING** 


Description Output from a .wmsg directive. 


value is out of range 


Description The value specified is outside the legal range. 


.var directive encountered outside macro 


Description The .var directive is legal inside macros (.macro/.endm) only. 


version number changed 


Description The operand of the .version directive does not match a 
previous .version directive or the —v command line option. 


Assembler Error Messages C-15 


Assembler Error Messages 


warning — block open at end of file 


Description A .block or .func directive is missing its corresponding 
.endblock or .endfunc. 


warning — function .sym required before .func 


Description A .sym directive defining the function should appear before 
the .func directive. 


warning — immediate operand not absolute 


Description Immediate operands should be absolute expressions. 
Action Refer to Table 3-2 on page 3-23. 
warning — line truncated 


Description Any characters after the 200th on an input line are ignored. 


warning — null string defined 


Description An empty string (one whose length = 0) is defined for string 
input for directives that require a null string operand. 


warning — register converted to immediate 


Description A constant was expected as an operand. 


warning — string length exceeds maximum limit 


Description The maximum length of the .title directive is 64 characters. 


warning — symbol truncated 


Description The maximum length for a symbol is eight characters. The 
assembler ignores the extra characters. 
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warning — trailing operand(s) 


Description The assembler found fewer or more operands than expected 
in the flagged instruction. 


warning — value out of range 


Description The value specified is outside the legal range. 


warning — value truncated 


Description The expression given was too large to fit within the instruction 
opcode or the required number of bits. 
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Linker Error Messages 


The linker issues several types of error messages: 


_) Syntax and command errors 
_j Allocation errors 
_} 1|/O errors 


This appendix discusses the three types of errors; they are listed 
alphabetically within each category. In these listings, the symbol (...) 
represents the name of an object that the linker is attempting to interact with 
when an error occurs. 


Syntax/Command Errors 


These errors are caused by incorrect use of linker directives, misuse of an 
input expression, or invalid options. Check the syntax of all expressions, and 
check the input directives for accuracy. Review the various options you are 
using and check for conflicts. 


absolute symbol (...) being redefined 


Description An absolute symbol cannot be redefined. 


adding name (...) to multiple output sections 


Description The input section is mentioned twice in the SECTIONS 
directive. 


ALIGN illegal in this context 


Description Alignment of a symbol can be performed only within a 
SECTIONS directive. 


D-1 


Syntax/Command Errors 


attempt to decrement DOT 


Description Statements such as .-= value are illegal. Assignments to dot 
can be used only to create holes. 


bad fill value 


Description The fill value must be a 16-bit constant. 


binding address for (...) redefined 


Description Only one binding value is allowed for each section. 


blocking for (...) redefined 


Description Only one blocking value is allowed for each section. 


—c requires fill value of 0 in .cinit (... overridden) 


Description C runtime conventions require the .cinit tables to be 
terminated with 0. 


can’t open filename 


Description Specified filename cannot be opened for some reason; file 
doesn’t exist, wrong file type, etc. 


Action Check spelling, pathname, environment variables, etc. 


cannot resize (...), section has initialized definition in (...) 


Description An initialized input section named .stack or .heap exists, 
preventing the linker from resizing the section. 


Syntax/Command Errors 


cannot specify a page for a section within a GROUP 


Description The SECTIONS directive GROUP option forces several 
output sections to be allocated contiguously. Therefore, you 
cannot specify a page for a section within a GROUP. 


cannot specify both binding and memory area for (...) 


Description The two are mutually exclusive. If you wish the code to be 
placed at a specific address, use binding only. 


command file nesting exceeded with file (...) 


Description Command file nesting is allowed up to 16 levels. 


-e flag does not specify a legal symbol name (...) 


Description The —e option requires a valid symbol name as an operand. 


entry point other than _c_int00 specified 


Description For —-c or —-cr option only. The runtime conventions of the 
compiler assume that_c_int00 is the one and only entry point. 


entry point symbol (...) undefined 


Description The symbol used with the —e option is not defined. 


errors in input — (...) not built 


Description Previous errors prevent the creation of an output file. 


fill value for (...) redefined 


Description Only one fill value is allowed per output section. Individual 
holes can be filled with different values with the section 
definition. 
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-i path too long (...) 


Description The maximum number of characters in an —i path is 256. 


illegal input character 


Description There is a control character or other unrecognized character 
in the command file. 


illegal memory attributes for (...) 


Description The attributes must be some combination of R, W, I, and X. 


illegal operator in expression 


Description Review legal expression operators. 


illegal option within SECTIONS 


Description The —I (lowercase L) is the only option allowed within a 
SECTIONS directive. 


invalid path specified with —i flag 


Description The operand of the —i flag must be a valid file or pathname. 


invalid value for —-f flag 


Description The value for -f must be a 2-byte constant. 


invalid value for —heap flag 


Description The value for -heap must be a 2-byte constant. 


invalid value for —stack flag 


Description The value for —stack must be a 2-byte constant. 
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invalid value for —v flag 


Description The value for —v must be a constant. 


length redefined for memory area (...) 


Description Each memory areain a MEMORY directive can have only one 
length. 


—m flag does not specify a valid filename 


Description You must specify a valid filename for the file you are writing 
the output map file to. 


memory area for (...) redefined 


Description Only one named memory allocation is allowed for each output 
section. 


memory page for (...) redefined 


Description Only one page allocation is allowed for each section. 


memory attributes redefined for (...) 


Description Only one set of memory attributes is allowed for each output 
section. 


missing filename on -I; use -I <filename> 


Description The —I (lowercase L) option requires the use of a filename 
operand. 
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misuse of DOT symbol in assignment instruction 


Description The dot symbol cannot be used in assignment statements 
that are outside SECTIONS directives. 


no input files 
Description The linker cannot operate without at least one input COFF file. 


—o flag does specify a valid file name : string 
Description The filename must follow the operating system conventions. 


output file has no .bss section 


Description This is a warning. This section is usually present in a COFF 
file. There is no real requirement for it to be present. 


output file has no .data section 


Description This is a warning. This section is usually present in a COFF 
file. There is no real requirement for it to be present. 


output file has no .text section 


Description This is a warning. This section is usually present in a COFF 
file. There is no real requirement for it to be present. 


origin missing for memory area (...) 


Description The origin is the beginning address for amemory range. Both 
the origin and length are required. 


origin redefined for memory area (...) 
Description The origin of a memory range has been redefined. 


Action Check to make sure that you haven’t named two memory 
ranges with the same name. 
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—r incompatible with —s (-s ignored) 

Description Since the —s option strips the relocation information and —r 
requests a relocatable object file, these options are in conflict 
with each other. 


section (...) not built 


Description The most likely cause of this is a syntax error in the 
SECTIONS directive. 


semicolon required after assignment 
Description There is a syntax error in the command file. 


statement ignored 
Description Caused by a syntax error in an expression. 


symbol referencing errors — (...) not built 


Description Symbol references could not be resolved. Therefore, an 
object module could not be built. 


symbol (...) from file (...) being redefined 


Description A defined symbol cannot be redefined in an assignment 
statement. 


too many arguments — use a command file 


Description You are limited to ten arguments on a command line or in 
response to prompts. 


too many -i options, 7 allowed 


Action Additional search directories can be specified with a C_DIR or 
A_DIR environment variable. 
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type flags for (...) redefined 


Description Only one section type is allowed per section. Note that type 
COPY has all of the attributes of type DSECT, so DSECT 
need not be specified separately. 


type flags not allowed for GROUP or UNION 


Description Special section types apply to individual sections only. 


—-u does not specify a legal symbol name 


Description The —u option must specify a legal symbol name that exists in 
one of the files that you are linking. 


undefined symbol in expression 


Description An assignment statement contains an undefined symbol. 


unexpected EOF (end of file) 


Description Syntax error in the linker command file. 


unrecognized option (...) 


Action Check the list of valid options. 


zero or missing length for memory area (...) 


Description Each memory range defined with the MEMORY directive 
must have a nonzero length. 


Allocation Errors 


Allocation Errors 


These error messages appear during the allocation phase of linking. They 
generally appear if a section or group does not fit at a certain address or if the 
MEMORY and SECTIONS directives conflict in some way. 


alignment for (...) must be a power of 2 
Description Section alignment must be a power of 2. 


Action In hexadecimal, all powers of 2 consist of the integers 1, 2, 4, 
or 8 followed by a series of zero or more Os. 


alignment for (...) redefined 


Description Only one alignment is allowed for each section. 


binding address (...) for section (...) is outside all memory on page 


(...) 


Description Each section must fall within memory configured with the 
MEMORY directive. 


Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 
ensure that no sections are being placed in unconfigured 
memory. 


binding address (...) for section (...) overlays (...) at (...) 
Description Two sections overlap and cannot be allocated. 


Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 
ensure that no sections are being placed in unconfigured 
memory. 
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binding address (...) incompatible with alignment for section (...) 


Description The section has an alignment requirement from an .align 
directive or previous link. The binding address violates this 
requirement. 


blocking for (...) must be a power of 2 
Description Section blocking must be a power of 2. 


Action In hexadecimal, all powers of 2 consist of the integers 1, 2, 4, 
or 8 followed by a series of zero or more Os. 


can’t align a section within GROUP - (...) not aligned 


Description The entire GROUP is treated as one unit, so the GROUP can 
be aligned or bound to an address, but the sections making up 
the GROUP cannot be handled individually. 


can’t align within UNION — section (...) not aligned 


Description The entire UNION is treated as one unit, so the UNION can be 
aligned or bound to an address, but the sections making up 
the UNION cannot be handled individually. 


can’t allocate (...), size ... (page ...) 


Description A section can’t be allocated, because no configured memory 
area exists that is large enough to hold it. 


Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 
ensure that no sections are being placed in unconfigured 
memory. 


Allocation Errors 


load address for uninitialized section (...) ignored 


Description Uninitialized sections have no load addresses—only run 
addresses. 


load address for UNION ignored 


Description UNION refers only to the section’s run address. 


load allocation required for uninitialized UNION member (...) 


Description UNIONS refer to runtime allocation only. You must specify the 
load address for all sections within a UNION separately. 


memory types (...) and (...) on page (...) overlap 

Description Memory ranges on the same page cannot overlap. 

Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 


ensure that no sections are being placed in unconfigured 
memory. 


no allocation allowed for uninitialized UNION member 


Description An uninitialized section with a UNION gets its run allocation 
from the UNION and has no load address, so no allocation is 
valid for the member. 


no allocation allowed with a GROUP-allocation for section (...) 
ignored 


Description The entire group is treated as one unit, so the group can be 
aligned or bound to an address, but the sections making up 
the group cannot be handled individually. 
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no load address specified for (...); using run address 


Description If an initialized section has a run address only, the section is 
allocated to run and load at the same address. 


no run allocation allowed for union member (...) 


Description A UNION defines the run address for all of its members; 
therefore, individual run allocations are illegal. 


output file (...) not executable 


Description The output file created may have unresolved symbols or other 
problems stemming from other errors. This condition is not 
fatal. 


PC-relative displacement overflow at address (...) in file (...) 


Description relocation of a PC-relative jump resulted in a jump 
displacement too large to encode in the instruction. 


section (...) at (...) overlays at address (...) 
Description The two sections overlap and cannot be allocated. 
Action If you are using a linker command file, check that the 


MEMORY and SECTIONS directives allow enough room to 
ensure that no sections overlap. 


section (...) enters unconfigured memory at address (...) 


Description A section can’t be allocated because no configured memory 
area exists that is large enough to hold it. 


Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 
ensure that no sections are being placed in unconfigured 
memory. 


Allocation Errors 


section (...) not found 


Description An input section specified in a SECTIONS directive was not 
found in the input file. 


section (...) won't fit into configured memory 


Description A section can’t be allocated, because no configured memory 
area exists that is large enough to hold it. 


Action If you are using a linker command file, check that the 
MEMORY and SECTIONS directives allow enough room to 
ensure that no sections are being placed in unconfigured 
memory. 


undefined symbol (...) first referenced in file (...) 


Description Unless the —r option is used, the linker requires that all refer- 
enced symbols be defined. This condition prevents the cre- 
ation of an executable output file. 


Action Link using the —-r option or define the symbol. 
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V/O and Internal Overflow Errors: 


The following error messages indicate that the input file is corrupt, nonexistent, 
or unreadable, or that the output file cannot be opened or written to. Messages 
in this category may also indicate that the linker is out of memory or table 
space. 


cannot complete output file (...), write error 


Description Usually means that the file system is out of space. 


cannot create output file (...) 
Description Usually indicates an illegal filename. 


Action Check spelling, pathname, environment variables, etc. The 
filename must conform to operating system conventions. 


can’t create map file (...) 
Description Usually indicates an illegal filename. 


Action Check spelling, pathname, environment variables, etc. The 
filename must conform to operating system conventions. 


can’t find input file filename 
Description The file, filename, is not in your PATH, is misspelled, etc. 


Action Check spelling, pathname, environment variables, etc. 


can’t open (...) 
Description The specified file does not exist. 


Action Check spelling, pathname, environment variables, etc. 


can’t read (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 
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can’t seek (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


can’t write (...) 
Description Disk may be full or protected. 


Action Check disk volume and protection. 


fail to copy (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


fail to read (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


fail to seek (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


fail to skip (...) 
Description The file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


fail to write (...) 
Description Disk may be full or protected. 


Action Check disk volume and protection. 
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file (...) has no relocation information 


Description You have attempted to relink a file that was not linked with —r. 


file (...) is of unknown type, magic number = (...) 
Description The binary input file is not a COFF file. 


illegal relocation type (...) found in section(s) of file (...) 


Description The binary file is corrupt. 


internal error (...) 


Description Indicates an internal error in the linker. 


invalid archive size for file (...) 


Description The archive file is corrupt. 


/O error on output file (...) 
Description Disk may be full or protected. 


Action Check disk volume and protection. 


library (...) member (...) has no relocation information 


Description Library members may not have relocation information; 
however, then they cannot satisfy unresolved references in 
other files when linking. 


line number entry found for absolute symbol 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 
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making aux entry filename for symbol n out of sequence 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


no string table in file filename 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


no symbol map produced — not enough memory 


Description This is anonfatal condition that prevents the generation of the 
symbol list in the map file. 


overwriting aux entry filename of symbol n 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


out of memory, aborting 


Description Your system does not have enough memory to perform all 
required tasks. 


Action Try breaking the assembly language files into multiple smaller 
files and do partial linking. Refer to Section 8.15 on page 8-58. 


relocation entries out of order in section (...) of file (...) 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 
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relocation symbol not found: index (...), section (...), file (...) 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


seek to (...) failed 
Description The input file may be corrupt. 


Action If the input file is corrupt, try reassembling it. 


too few symbol names in string table for archive n 
Description The archive file may be corrupt. 


Action If the input file is corrupt, try recreating the archive. 
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Hex Conversion Utility Examples 


This section contains eight examples that will illustrate the development of 
command files for a variety of memory systems and situations. 


Topic Page 
E.1 Building a Command File for Two 16-Bit EPROMS ................ E-3| 
E.2 Building a Command File for Booting From the ’C4x 

CommunicationSiPonterneee er eee eer reert er en ee t htt err ttt 
E.3 Building a Command File to Convert Code fora ’C32 ............ [E-15| 
E.4 Building a Command File for a Four 8-Bit EPROM System ....... 
E.5 Avoiding Holes Between Multiple Sections ..................055 E-21 
E.6 Building a Command File for a C31 Serial Port Boot Load ....... [E-23| 
E.7 Dealing With Three Different Addresses ..............00eeu neues 
E.8 Building a Command File to Generate a Boot Table fora ’C32 ... .|E-26] 
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Sample ASM Code 


All examples use the assembly code in Example E-1. 


Example E-1. Sample ASM Code 


; Sample ASM file A 

a a a a Ea IR a RT a , 

a aa a a a IR Nc I a a r 

; Assemble two words into section secl } 

ee a ey se ee ee ee , 
sect “secl” 


.word 12345678h 
.word 12345678h 


-sect "sec2” 
-word Oaabbccddh 
-word Oaabbccddh 
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Building a Command File for Two 16-Bit EPROMs 


E.1 Building a Command File for Two 16-Bit EPROMs 


This example illustrates how to build the hex command file necessary to 
convert a COFF object for the memory system shown in Figure E—1. In this 
system, there are two external 128K x16-bit EPROMs interfacing with a 
’C8x/’C4x target processor. Each EPROM contributes 16 bits toward making 
a single, 32-bit word for the target processor. 


Figure E-1. System With Two 16-bit EPROMs 


. Upper 16 Bits 
Lower 16 Bits 
<4 
CPU 
*C8x or ’C4x 
128Kx16 128Kx16 
ROMO ROM1 


Width 32 Bits 
ROM Width ROM Width 
16 Bits 16 Bits 


EPROM System Memory Width 32 Bits 


As an added requirement for this application, code linked at load address 
0x300000 must actually reside in physical EPROM address 0x10. The 
circuitry of the target board handles the translation of this address space. 


By default, the hex conversion utility will use the linker load address to 
generate addresses in the converted output file. For this application, the code 
will reside at an address (0x10) that is different than the one specified by the 
linker (0x300000). The paddr parameter places a section at a location different 
than the linker load address. This will effect the burn of code at EPROM ad- 
dress 0x10. When using paddr, you must use it for all sections and ensure that 
the specified addresses do not cause overlap of the linker-assigned section 
load addresses of sections that follow. 


In this example, two sections are defined: sec1 and sec2. Therefore, it is not 
difficult to add a paddr option for each of these sections. However, the task 
may become unmanageable for large applications with many sections, or in 
cases where section sizes may change often during code development. 
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To work around this problem, you can combine the sections at link stage, 
creating a single section for conversion. The linker command file that accom- 
plishes this is shown in Figure E-2. 


Figure E—2. Linker Command File for Two 16-bit EPROMs 


/* */ 
/* Sample Linker Command file for Example 1 */ 
feosesbeece se sbeeesesees—e - Sool poses / 
test .obj 

=O a.0uUt 


-m test.map 


/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 
{ 


RAM: org = 0x300000 len = 0x100 
} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 


SECTIONS 
{ 
outsec: {*(secl) 
*(sec2) } > RAM 


The EPROM programmer used in this application requires Intel format and 
byte addressing. Application requirements include: 


Data in a COFF file that is 32 bits wide 

The EPROM system memory width must be 32 
ROM1 contains the upper 16 bits of the words 
ROMO contains the lower 16 bits of the words 
Locate code starting at EPROM address 0x10 
Intel format for EPROM programmer 

Byte addresses must be used in the output file 


OOOCCUL 


To satisfy the requirements of the EPROM programmer, use the —i and —-byte 
options. The -i option selects conversion to Intel format. The —byte option 
causes addresses to be incremented by byte rather than by the system 
memory width. 
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-datawidth 32 


-byte 
-memwidth 32 


—romwidth 16 


Building a Command File for Two 16-Bit EPROMs 


To meet the requirements of the memory system, select the following options: 


/* This is default and refers to relevant size of raw data 
contained in the COFF input file */ 


/* use byte increment for addresses in converted output file */ 


/* Physical width of EPROM system */ 


/* Physical width of ROM device */ 


The —memwidth 32 option tells the hex conversion utility that the system 
memory width is 32 bits. This corresponds to the EPROM system memory 
width, as described in Figure E—1. The -romwidth option specifies the width 
(in bits) of the physical ROM device. You can set the option globally since the 
width of both ROM devices is the same. 


With the memory width and ROM width values above, the utility will automati- 
cally generate two output files. The ratio of memory width to ROM width deter- 
mines the number of output files. One file contains the lower 16 of the 32 bits 
of raw data and the other contains the upper 16 bits of the corresponding data. 


Example E—2 shows the command file with all of the selected options. 
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Example E-2. Command File for Two 16-bit EPROMs 


a.out /* COFF object input file ba 

-map tutorl.mxp /* Create a map of converted output */ 

[$i eons eS eo SS Se ee Se ee */ 

/* Set parameters for EPROM programmer */ 

JRtee ee a os 8 */ 

-i /* Select Intel format a 

-byte /* Select byte addressing for output file*/ 

[Peesn ees 2 Sh Se a ogo oe Se Sh ee */ 
/* Set options required to describe EPROM system * / 

Ye en a SE aL * / 
-datawidth 32 /* Set relevant data width for COFF file */ 

-memwidth 32 /* Set EPROM system memory width x] 

-romwidth 16 /* Set physical width of ROM devices */ 

ROMS 


{ 


EPROM: origin = 0x10, length = 0x30, 
files = { lowl6.byt , uppl6.byt } 
} 


SECTIONS 

{ 

outsec: paddr=0x10 
} 
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Figure E-3 shows the contents of the converted file for ROMO (low16.bit) 
which contains the lower 16 bits, and the contents of the converted file for 
ROM1 (upp16.bit) containing the upper 16 bits of data. Note that the 
addresses specified in the hex output files have been multiplied by a factor of 
two because of the —byte option. With byte addressing, the hex conversion 
utility expanded the 16-bit word address provided by paddr to the appropriate 


byte address. For more information, see Section 10.10. 
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Figure E—3. Data From Output File resulting from Example E-2 
(a) low16.bit:( Lower Bits) 


Data from converted output file 


:0800200056785678CCDDCCDDEA 
:00000001FF 


Corresponding Map in EPROM — ROMO (See Example E-1) 


0x20 


(b) upp 16. bit: (upper bits) 


Data from converted output file 


:0800200012341234AABBAABB82 
:00000001FF 


Corresponding Map in EPROM — ROM1 (See Example E-1) 
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Building a Command File for Two 16-Bit EPROMs 


To illustrate precisely how the utility performs the conversion, specify the —-map 
option. Although not required, the —-map option generates useful information 
about the output. The resulting map is shown in Example E-3. 


Example E-3. Hex Conversion Map File Resulting From Example E-2 


KKK KKK KKK KKK KKK KK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KK 


TMS320C3x/4x Hex Converter Version X.XX 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKEK 


Mon Nov 14 15:00:56 1997 


INPUT FILE NAME: <a.out> 
OUTPUT FORMAT: Intel 


PHYSICAL MEMORY PARAMETERS 
Default data width: 32 
Default memory width: 32 
Default output width: 16 


OUTPUT TRANSLATION MAP 


00000010..0000003f Page=0 ROM Width=16 Memory Width=32 ”EPROM” 


OUTPUT FILES: lowl6.byt [b0..b15] 
uppl6.byt [b16..b31] 


CONTENTS: 00000010..00000013 Data Width=4 outsec 
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E.2 Building a Command File for Booting From the 
*C4x Communications Port 


This example uses the same sample code given in Example E-1, but will be 
converting the code for the EPROM system shown in Figure E-4. 


Figure E-4. A Sample EPROM System for a 'C4x 


Parent 128Kx8 
*C4x 
CPU 


ROM Width 8 Bits 


a———— sw 


EPROM System Memory 
Width 8 Bits 


This application involves two ’C4x devices. One acts as a parent and boots 
the second (child) processor via the communications port. The child 
processor’s boot table is stored in an external EPROM connected to the 
parent. 


The parent processor reads the boot table for the child processor from the 
EPROM and writes this data to communications port 0. The child’s on-chip 
boot loader reads the code from communications port 1 and writes it starting 
at location 0x4000 0000. 


Once the boot process has completed on the child processor, the child code 
located in section sec1 copies section sec2 to location Ox2ff800 for faster 
execution. 


The parent ’C4x device, as shown in Figure E—4, requires the boot table to 
load at ROM address 0x100. 
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Example E-4. Linker 
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The linker command file in Example E—4 specifies the appropriate run and 
load addresses for the code. In the command file, the load address and run 
address for sec1 is set to >= 0x40000000. Section sec2 will load at address 


>= 0x40000000 but it will run at location Ox2ff800. 


Command File for Booting From the ’C4x COMM Port 


/* Sample Linker file for Example 2 


/* 


test.obj 
-O a.out 
-m test.map 


/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 

{ 

INT: org = 0x2ff800 len = 0x400 
EXT: org = 0x40000000 len = 0x400 


} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY 


SECTIONS 

{ 

secl: {} > EXT 

sec2: {} load = EXT, run = INT 


} 


*/ 


The EPROM programmer requires only that the Intel format be used. To 


satisfy this requirement, use the — option. 


System requirements include: 


32-bit wide data in the COFF file 
8-bit wide EPROM system memory 


Boot table location at parent ROM address 0x100 
Intel format for converted file 


OOCOUdCOd 


A boot table suitable for the communications port boot load 


Single output file containing converted data for a 128K x 8-bit EPROM 
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To satisfy the conditions for boot table generation and the requirements for the 
EPROM system, select the following options: 


-datawidth 32 /* This default value refers to the we 
/* relevant size of the raw data */ 
/* contained in the COFF input file */ 
-memwidth 8 /* Physical width of EPROM system */ 
-romwidth 8 /* Physical width of each EPROM device */ 
—-boot /* Generate a Boot Table */ 


-bootorg COMM /* Use Boot Table format suitable for */ 
/* communications port boot load */ 


The —memwidth option sets the EPROM system memory width. According to 
the system memory configuration shown in Figure E—4, this value is eight bits 
wide. Similarly, using the —romwidth option sets the physical width of the 
EPROM device. The —boot option tells the hex conversion utility to generate 
a boot table and -bootorg COMM creates a boot table suitable for comm port 
loading. 


Using these values for memory width and ROM width, the utility creates a 
single output file, since the number of output files is determined by the ratio 
of memory width to ROM width. 


Finally, the converted file must initiate boot-table loading at address 0x100 in 
the ROM device. Use the ROMS directive to control the placement of the boot 
table in the EPROM connected to the parent processor. The hex conversion 
utility will use the origin specified in the ROMS directive as the base address 
for the boot table. 


Example E—5 shows the command file that includes all of the selected options. 
Note the command file also shows options —cg, —cl, ivtp, and —iack, which 
define values for control registers. 


The values used in this example are not real; they are not valid quantities for 
any real physical system. These options are used only to provide an 
illustration. Each individual target board and application require unique values. 


To define the entry point, the address to which the boot loader will branch for 
execution upon completing the boot process, use the —e option. 
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Example E—5. Command File for Booting From the 'C4x COMM Port 


[#aeno Sen shee ab ese Ss ee So ee ee et ee en */ 
/* Sample Hex Conversion Utility Command File for Example 2 */ 
IR ee */ 
a.out /* COFF object input file * / 
-map tutor2.mxp /* Create a map of converted output */ 
Yihiceesgt oa oe ee tee ee ee Sa ee ee ee */ 
/* Set parameters for EPROM programmer yd 
J $eeeenaae eases sen aeeee nee ase se seen sSee Se eo ee eee */ 
-i /* Select Intel format ay 
Je Sek See es a ee ee ee ee ee ee eee */ 
/* Set options required to describe EPROM system */ 
[*¥ssSena3555555Ssn asses Sse sa ses se sense en een sn se seen se es */ 
-datawidth 32 /* Set raw data size from COFF */, 
-memwidth 8 /* Set parent EPROM system memory width */ 
-romwidth 8 /* Set physical width of ROM devices * / 
J ¥ see onsen ese ose sheen ee sh een eee eS */ 
/* Set options for Boot Table generation *«/ 
Y Piece eS ar ee ed eee */ 
-boot /* Generate boot table ay 
-bootorg COMM /* Use Boot Table format suitable for load 
from communications port */ 
-cg 0x11111111 /* Set child Global Bus Control Register */ 
-cl 0x22222222 /* Set child Local Bus COntrol Register e/ 
-ivtp 0x00300000 /* Set child Interrupt Vector Location #i 
-tvtp 0x00400000 /* Set child Trap Vector Location 7 
-iack 0x00500000 /* Set child IACK acknowledge location * / 
-e 0x40000000 /* Set entry point ia 
ff Rac i a ee */ 
/* Use ROMS directive to set load location for boot table */ 
/* on ROM device (parent processor) xf 
fice ce a ee */ 
ROMS 
EPROM: origin = 0x100, length = Ox1FFOO0, files = { boot.tbl } 
SECTIONS 
secl:paddr=boot 
sec2:paddr=boot 
/* If SECTIONS directive is used, -boot option is ignored and you need to specify 
= boot; refer to section 10.6. */ 
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Figure E—5 shows the converted output generated by the command file. The 
linker-assigned load address is used as the destination address for each of the 
sections included in the boot table. The boot loader places the code at the 
linker load address. Notice that although a run address is specified for sec2, 
the run address does not appear anywhere in the file. This is because the hex 
conversion utility operates on load addresses only. It ignores run addresses 
because they have no meaning in the context of the converted file. 


Figure E—5. Data From Output File (boot.tbl) resulting from Example E—5 
(a) Data from converted output file 


>18010000111111112222222202000000000000407856341278563412B1 
:200118000200000002000040DDCCBBAADDCCBBAA00000000000003000000400000005000A7 
:00000001FF 


(b) Corresponding Map in EPROM — ROM1 (See Example E-1) 


0x100 
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Example E-6. Map File Resulting From Example E-5 


KKK KK KKK KKK KKK KK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KEK KKK KKK KKK KKK KKK KK KK 


* TMS320C3x/4x Hex Converter Version X.XX * 
KKK KKK KK KKK KKK KK KKK KK KKK KKK KK KKK KK KKK KKK KKK KK KKK KKK KK KKK KKK KKKKKAKKKKK KKK 


Tue Nov 15 10:34:43 1997 


INPUT FILE NAME: <a.out> 
OUTPUT FORMAT: Intel 


PHYSICAL MEMORY PARAMETERS 

Default data width: 32 

Default memory width: 8 (LS-—-—>MS) 
Default output width: 8 


BOOT LOADER PARAMETERS 

Table Address: COMM PORT 

Entry Point: 40000000 

Global Memory Configuration: 11111111 

Local Memory Configuration: 22222222 

Interrupt Vector Table Pointer (IVTP): 00300000 
Trap Vector Table Pointer (TVTP): 00400000 

IACK Location: 00500000 


OUTPUT TRANSLATION MAP 


00000100..0001fff£ Page=0 ROM Width=8 Memory Width=8 “EPROM” 


OUTPUT FILES: boot.tbl [b0..b7] 


CONTENTS: 00000100. .00000137 BOOT TABLE 
secl : dest=40000000 size=00000002 width=00000004 
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E.3 Building a Command File to Convert Code for a ’C32 


This example creates a hex command file to convert code for a ’C32. A ’C32 
can access 8-, 16-, or 32-bit external data. Figure E-6 shows a memory 
system that with a C32 processor that accesses memory on a single, 16-bit 
EPROM using STRBO and STRB1. The EPROM will contain applications 
code stored as 32-bit data (STRBO) and a set of coefficient tables used by the 
applications code that is stored as 8-bit data (STRB1). 


Figure E-6. Sample EPROM System for a ’C32 


16K x 16 32-bit data 


8-bit data 


ROM Width 16 Bits 


————7-—_— 


EPROM System Memory Width 16 Bits 


Sample code in Example E—1 is used here. However, in this situation, it has 
been linked so that code and data in seci1 is allocated in an address space 
starting at address 0x0 where STRBO is active and sec2 is allocated at ad- 
dress 0x9000000 where STRB1 is active. The linker command file used is 
shown in Example E-7. 
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Example E-7. Linker Command File for a ’C32 


/* m7. 
/* Sample Linker Command file for Example 3 baer 
[* / 
test.obj 
-o a.out 


—-m test.map 


/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 

{ 

STRBO: org = 0x0000 len = 0x1000 
STRB1: org = 0x900000 len = 0x1000 
} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 
SECTIONS 

{ 

secl: {} > STRBO 


sec2: {} > STRB1 
} 


System requirements include: 


16-bit wide system memory 

Physical EPROM width of 16 bits 

Data width of application code measuring 32 bits (sec1) 

Data width of coefficient tables measuring 8 bits (Sec2) 
Applications code is loaded at EPROM address 0 (STRBO) 
8-bit data tables loaded at EPROM address 0x2000 (STRB1) 
Intel format for EPROM programmer 


OOCOUOCL 


The data widths for sec1 and sec2 are not the same. Because these sections 
will be loaded at EPROM addresses different than those specified at link time, 
you must use a ROMS and SECTIONS directive. 


The data widths and load addresses can be specified for each section using 
datawidth and paddr attributes for the sections. 
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n 


ECTIONS 


secl : datawidth=32, paddr=0x0 


sec2 : datawidth=8, paddr=0x2000 
} 


This SECTIONS directive sets the EPROM load address via paddr and sets 
the data width size using — datawidth for each of the sections. Note that select- 
ing the datawidth effects the output. The datawidth determines the size of the 
data that is considered relevant in the raw data contained in the COFF input 
file. All raw data in the COFF input file is 32 bits wide, the native width of the 
target ‘C32. 


When data width is set to 32, the hex conversion utility uses the entire 32 bits 
of raw data in the COFF input. When data width is set to a value <32, then the 
raw data is truncated to the appropriate size before translation into the re- 
quired data format. The assembly code for sec2 is: 


-sect “sec2” 
-word Oaabbccddh 
-word O089abcdefh 


With the data width set to 8, the utility will take only the lower 8 bits of the data 
word for translation. The upper 24 bits bits are discarded. Therefore, each of 
the words defined will be truncated to Oxdd,0xef, respectively. 


The data width value also affects the addresses in the output file. The 32-bit 
data words for seci are broken up into successive 16-bit words for loading on 
the EPROM. The 8-bit data words for the tables in sec2 will be packed into the 
16-bit words of the EPROM. 


In the load of sect, the addresses in the hex output file will be expanded by 
a factor of two, determined by the ratio of data width to memory width. 
Whereas for the load of sec2, the address space will be divided by a factor of 
two, again determined by the ratio of data width to memory width. For a 
detailed explanation of the effects of data width and memory width on the ad- 
dress space, please refer to Section 10.10. 


The —memwidth option sets the system memory width. For the memory sys- 
tem described in Figure E-6, this is 16 bits (-memwidth 16). The —romwidth 
option sets the physical EPROM width, which is also 16 bits (-romwidth 16). 
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Example E—8 shows the resulting command file with all the options necessary 
to convert the COFF file for the EPROM system in Figure E-6. 


Example E-8. Sample Hex Command File for a ’C32 


PRs eee sess Ss Se ee a ee ee */ 
/* Sample Command File for Example 3 */ 

J¥osaaeaseasesee ses l eo Se eee se ee SS Se eS */ 
a.out /* COFF object input file * / 
-map tutor23.mxp /* Create a map of converted output ay: 
/* ereereent pps eee pene! a2 ese, ere een a) 
/* Set parameters for EPROM programmer af 
J Pees ees SS Se ee Se SS ee eee ee ee */ 
-i /* Select Intel format aA 
/* epee grote, peeeeveent see Sees eran per ene eee Sate ey 
/* Set options required to describe EPROM system */ 
f Pees eee see es ee ee Se ee ee eee ee */ 
-memwidth 16 /* Set EPROM system memory width */ 
-romwidth 16 /* Set physical width of ROM devices a7 
ROMS 

EPROM: origin = 0x000, length = 0x4000, files = { tutor3.hex } 

SECTIONS 

secl:paddr=0x0, datawidth=32 

sec2:paddr=0x2000, datawidth=8 


Figure E—7 displays the contents of the hex output file tutor3.hex. 
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Figure E—7. Data from Hex Output File (tutor3.hex) Resulting From Example E-8 


:080000005678123456781234D0 
:02200000DDDD24 
:00000001FF 


0x2000 


Note that the 32-bit words in section seci1 have been broken into successive 
words for loading to the EPROM. Note also that the truncated data from sec2 
has been packed into a single 16-bit EPROM word. 
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E.4 Building a Command File for a Four 8-Bit EPROM System 


This example provides a set of commands for generating conversion files for 
four 8-bit EPROMs 


The command file in Example E—9 will generate separate files for four 8-bit 
EPROMs that will be used to form the 32-bit data for a ’C3x or ’C4x processor. 


_) Note that the load address becomes the output file address, and 


(1 The EPROM address for each of the files is the same because the 
processor will fetch one byte from each of the four ERPROMs simulta- 


neously to form one 32-bit word. 


Example E-9. Code for Four 8-Bit EPROM Files 


-i /* Intel format */ 

a.out /* COFF file input Ke. 

-map example.mxp /* Generate a map file ROMS * 
{ 

ROM : org = 0x0, length = Oxffffffff, 


/* Ay: 
Pe Set Physical Width of EPROM to 8 bits */ 
/* */ 
romwidth = 8, 

/* + 
[* Set Memory Width of EPROM system to 32 bits */ 
/* */ 
memwidth = 32, 

[* */ 


/* The following directive specifies the names of */ 

/* the output files where converted data is to be */ 

/* stored. The hex conversion utility will store byte 0 in the 
/* first file , byte 1 in the next, etc.. Use of */ 


/* this directive is optional. */ 
fF a 
files = { 


example.b0, example.bl, example.b2, example.b3 } 


} 


*/ 
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E.5 Avoiding Holes Between Multiple Sections 


When the memory width is less than the data width, holes may appear at 
the beginning of a section or between sections. This is caused by multi- 
plication of the load address by a correction factor. 


If itis necessary to eliminate the holes between converted sections, they 
can be made contiguous in one of two ways. 


Specify a padar for each section listed in a SECTIONS directive. This 
forces the hex conversion utility to use that specific address for the output 
file address field. A sample command file to do this is shown in 
Example E—11. 


If there are many sections, this can become tedious as itis necessary also 
to ensure that the addresses will not overlap. To avoid this problem, link 
the sections together into one output section for conversion. 


Example E-12 shows a sample linker command file that illustrates how 
this can be done. The linker should be executed using this command file 
before executing the hex conversion utility with the set of commands that 
appear in Example E-13. 


Example E-10. Linker Command File for Avoiding Holes: Method One 


} 


{ 


} 


/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 

{ 

RAM: org = O0x2ff800 len = 0x0400 
SRAM: org = 0x80000000 len = 0x1000 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 


S] 


ECTIONS 
secl : load = SRAM 
sec2 : load = SRAM, run = RAM 
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Example E—11. Hex Conversion Utility Command File for Avoiding Holes: Method One 


=a 
a.out 
-map example.mxp 


ROMS 


ROM : org = 0x000, length = 0x800, romwidth = 16, memwidth = 16 


SECTIONS 


secl : paddr = 0x000 
sec2 : paddr 0x004 


Example E-12. Linker Command File for Avoiding Holes: Method Two 


/* SPECIFY THE SYSTEM MEMORY MAP if 


MEMORY 


{ 
ROM: org = 0x000004 len = 0x1000 /* INTERNAL ROM */ 


} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY ff 
SECTIONS 

{ 

outsec : { *(secl) 


*(sec2) } > ROM 
} 


Example E-13. Hex Conversion Utility Command File for Avoiding Holes: Method Two 


= 
a.out 
-map example.mxp 


ROMS 


ROM : org = 0x100, length = 0x800, romwidth = 16, memwidth = 16, 
files = {example.hex} 


SECTIONS 


outsec : paddr = 0x100 
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E.6 Building a Command File for a ’C31 Serial Port Boot Load 


Example E—14 shows a hex command file for generating a boot load table 
for the ’C31 serial port. 


Example E-—14. Command File for a 'C31 SERIAL Port Boot Load 


a.out /* COFF file input */ 

-i /* Intel format */ 

-romwidth 32 

-map example.mxp /* Generate a map file */ 

—boot 

-bootorg SERIAL 

-cg 0x12345678 /* This value is board specific */ 
-o example.hex 


In this example, the output file locates the start of the boot table at the load 
address of the first bootable section in the COFF input file. This is because no 
ROMS directive was specified. 
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E.7 Dealing With Three Different Addresses 


Building a boot table may require that you specify three different 
addresses: 


H Boot Table Load Address 
m Applications Code Load Address 
B Applications Code Run Address 


Some applications may require that after the booting process completes, 
you move the code loaded into one area of memory (applications code 
load address) to a different memory location for execution (applications 
code run address). For example, for faster code execution, you may move 
code that was boot loaded into an external memory location to internal 
memory. 


The linker is used to define the load and run addresses for the applications 
code. You can use the hex conversion utility to build the boot table and as- 
sign its address in the output file. 


Example E—15 shows the linker command file needed to specify the load 
and run addresses for the applications code. The linker load address 
serves as the destination address for the section that will appear in the hex 
conversion utility’s boot table. The linker resolves all symbol references 
with respect to the run address specified, but this address will not appear 
in the hex output file. Notice that the linker command file defines two sec- 
tions. Section sec1 contains the code that will copy sec2 to on-chip 
memory. 


Example E-15. Linker Command File for Dealing With Three Different Addresses 
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/* SPECIFY THE SYSTEM MEMORY MAP */ 


MEMORY 

{ 

RAM: org = 0x2ff800 len = 0x0400 
SRAM: org = 0x80000000 len = 0x1000 
} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 


SECTIONS 

{ 

secl : load 
sec2 : load 


} 


SRAM 
SRAM, run = RAM 


Dealing With Three Different Addresses 


Example E—16 shows the command file that will build the boot table. The 
address for the boot table can be controlled by either using a ROMS direc- 
tive or using the -bootorg option. We are using the —bootorg option. 


Example E—16. Hex Command File for Dealing With Three Different Addresses 


a.out /* COFF file input */ 


-i /* Intel format */ 

-memwidth 8 

-romwidth 8 

-map sample.mxp /* Generate a map file */ 
—boot 

-bootorg 0x4000000 

-ceg 0x11111111 /* Target Board Dependent */ 
-—cl 0x22222222 /* Target Board Dependent */ 
-ivtp 0x06000000 /* Target Board Dependent */ 
-tvtp 0x06200000 /* Target Board Dependent */ 
-iack 0x04000000 /* Target Board Dependent */ 
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E.8 Building a Command File to Generate a Boot Table for the C32 


This example illustrates a command file that generates a boot table and a 
coefficient/data table for a sample EPROM system (shown in Figure E-8). 
This example is applicable to ’C32 only, since it requires varying data widths. 


Figure E-8. Sample EPROM System for a ’C32 
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STRB1 


128Kx32 


Boot Table 


C32 (32-bit data) 


10000 


Coefficients 
(16-Bit data) 


ROM Width 32 Bits 


—_— 


EPROM System Memory Width 32 Bits 


In this example, the boot table is treated as 32-bit data, but the coefficient data 
table is treated as 16-bit data. Both boot and coefficient tables will be in 
memory where STRB1 is active. The boot table header contains records for 
each STRB control register that sets the desired value for that register at boot. 
The boot loader resets the control registers to these values once boot load 
completes. 


The values for these registers can be set using the —strb0, —strb1, and —iostrb 
options to set the STRBO, STRB1, and IOSTRB registers, respectively. In 
addition to the STRB values given in the boot table header, there is also a word 
at the start of each source block that contains the proper STRB configuration 
for that block. This enables you to configure a STRB control register for each 
source block, since the destination and data sizes vary for each block. The hex 
conversion utility will create this word automatically, basing it on the EPROM 
system memory width and data width of each bootable section. For a more 
detailed explanation of the on-chip boot loader process, refer to the 
TMS320C32 User’s Guide, Section 3.4. 


Example E—17 shows the linker command file used to build the application. 
Both applications code and data will be accessed via STRB1. 
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Example E-17. Linker Command File for a ’C32 


test.obj 
-O a.out 
-m test.map 


/* SPECIFY THE 


MEMORY 
{ 
STRBO: 
STRB1: 
} 


/* SPECIFY THE SECTIONS ALLOCATION INTO MEMORY */ 


SI 
{ 


ECTIONS 


secl: 
sec2: 


SYSTE 


MM 


EMORY MAP */ 


0x1000 
0x200000 


org = 0x00000 len 
org = 0x900000 len 


{} load 
{} load 


0x900000 
0x910000 


Example E—18 displays the command file used to convert the COFF file for 
Intel format, creating a boot table for the applications code contained in sec1 
and converting the coefficient/table data in sec2. Note that the 16-bit data val- 
ues in sec2 will be packed into the 32-bit words of the EPROM. 
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Example E-18. Hex Command File For a ’'C32 Boot Table 


/Roese secs sack se eh ase sees ssn ek sess sess Se eee Shee eee ee eee e eee eH estes */ 
/* Sample Hex Conversion Utility Command File for Example 8 mp 
/* This hex command file creates a boot table */ 
/* and also converts a data section for burning ay 
/* on a32-bit wide EPROM. This example is */ 
/* valid for 'C32 only since variable datawidths */ 
/* are used. */ 
J Pee ete se eS ee ee ee ee ee ee */ 
a.out /* COFF object input file * 
-map example8.mxp /* Create a map of converted output ab 
—-o example8.hex /* output file name He); 
[ee ee ee ee ee ee */ 
/* Set parameters for EPROM programmer sd 
[Pte ee ee ee os Se ee se ee ee See aes */ 
-i /* Select Intel format + 
a a ea */ 
/* Set options required to describe EPROM system * / 
Jee ie ee ee ee ee eee eh eee ee ee ee hee */ 
-memwidth 32 /* Set EPROM system memory width xf 
-romwidth 32 /* Set physical width of ROM devices Hf 
* */ 
/* Set options required for boot table generation */ 
L* Rf: 
-bootorg 0x000000 /* Bet address origin for boot table ar 
-strbl1 0xD0000 /* Set value for STRB1 

ROMS 

EPROM: origin = 0x000, length = 0x4000, files = { tutor3.hex } 

SECTIONS 

secl:paddr=boot, datawidth = 32 

sec2:paddr=0x10000, datawidth = 16 
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——__—Qaeererrvvmnmnmaieereeeereerererrererereerwrerereeoererereererereerererreeeererereoeerml 
Note: Values and data sizes 


In this example, that the value of STRB1 is set to OxDOO00. This implies a 
memory size of 32 bits and a data size of 16. This will be the setting for 
STRB1 after the boot load is complete. For program fetches to occur correct- 
ly, the PRGW pin must be set to 1 so that two consecutive 16-bit reads are 
done to form a single program word. For more information about the PRGW 
pin strobe control registers, refer to the TMS320C32 User's Guide. 
ee) 


Figure E—9 shows the contents of the output file, example8.hex. Note that the 
hex conversion utility automatically created the correct data word for the 
STRB setting for the source block containing sec1. 


Hex Conversion Utility Examples E-29 


Building a Command File to Generate a Boot Table for the ‘C32 


Figure E—9. Output File for Example 8 (example8.hex) Resulting From Example E-18 


:20000000000000200000000000000000000D000000000002009000000F0000681234567896 
:0800008001234567800000000DC 


02000000400001F9 


:04000000ccppccppaa_ —«OXO_ |_000000020 
:00000001FF 00000 0000 
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Glossary 


absolute address: An address that is permanently assigned to a memory 
location. 


absolute section: A named section defined with the .asect directive. All 
addresses except those defined with .labelin an absolute section are ab- 
solute. 


alignment: A process in which the linker places an output section at an ad- 
dress that falls on an n-bit boundary, where nis a power of 2. You can 
specify alignment with the SECTIONS linker directive. 


allocation: A process in which the linker calculates the final memory 
addresses of output sections. 


archive library: A collection of individual files that have been grouped into 
a single file. 


archiver: A software program that allows you to collect several individual 
files into a single file called an archive library. The archiver also allows 
you to delete, extract, or replace members of the archive library, as well 
as add new members. 


assembler: A software program that creates a machine-language program 
from a source file that contains assembly language instructions, 
directives, and macro directives. The assembler substitutes absolute op- 
eration codes for symbolic operation codes, and absolute or relocatable 
addresses for symbolic addresses. 


assembly-time constant: A symbol that is assigned a constant value with 
the .set directive. 


assignment statement: A statement that assigns a value to a variable. 


autoinitialization: The process of initializing global C variables (contained 
in the .cinit section) before beginning program execution. 


F-1 


Glossary 


F-2 


auxiliary entry: The extra entry that a symbol may have in the symbol table 
and that contains additional information about the symbol (whether the 
symbol is a filename, a section name, a function name, etc.). 


binding: A process in which you specify an address for an output section or 
a symbol. 


block: A set of declarations and statements that are grouped together with 
braces. 


-bss: One of the default COFF sections. You can use the .bss directive to 
reserve a specified amount of space in the memory map that can later 
be used for storing data. The .bss section is normally uninitialized. 


C compiler: A program that translates C source statements into floating- 
point assembly language source statements. 


command file: A file that contains linker options and names input files for 
the linker. 


comment: A source statement (or portion of a source statement) that is 
used to document or improve readability of a source file. Comments are 
not compiled, assembled, or linked; they have no effect on the object file. 


common object file format (COFF): A binary object file format that 
promotes modular programming by supporting the concept of sections. 


conditional processing: A method of processing one block of source code 
or an alternate block of source code, based upon the evaluation of a 
specified expression. 


configured memory: Memory that the linker has specified for allocation. 
constant: A numeric value that can be used as an operand. 


cross-reference listing: An output file created by the assembler that lists 
the symbols that were defined, what line they were defined on, which 
lines referenced them, and their final values. 


.data: One of the default COFF sections. The .data section is an initialized 
section that contains initialized data. You can use the .data directive to 
assemble code into the .data section. 
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directive: Special-purpose commands that control the actions and 
functions of a software tool (as opposed to assembly language 
instructions, which control the actions of a device). 


emulator: A hardware development system that emulates 
TMS320C3x/C4x operation. 


entry point: The starting execution point in target memory. 


executable module: An object file that has been linked and can be 
executed in a TMS320C3x/C4x system. 


expression: A constant, a symbol, or a series of constants and symbols 
separated by arithmetic operators. 


external symbol: A kind of symbol that is either 1) defined in the current 
module and accessed in another, or 2) accessed in the current module 
but defined in another. 


field: For the TMS320C3x/C4x, a software-configurable data type whose 
length can be programmed to be any value in the range of 1-16 bits. 


fileheader: Aportion ofa COFF object file that contains general information 
about the object file (such as the number of section headers, the type of 
system the object file can be downloaded to, the number of symbols in 
the symbol table, and the symbol table’s starting address). 


global: A kind of symbol that is either 1) defined in the current module and 
accessed in another, or 2) accessed in the current module but defined 
in another. 


GROUP: An option of the SECTIONS directive that forces specified output 
sections to be allocated contiguously (as a group). 


hex conversion utility: A utility that converts COFF object files into one of 
several standard ASCII hexadecimal formats, suitable for loading into an 
EPROM programmer. 
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high-level language debugging: The ability of a compiler to retain sym- 
bolic and high-level language information (such as type and function 
definitions) so that a debugging tool can use this information. 


hole: An area between the input sections that compose an output section 
that contains no actual code or data. 


incremental linking: Linking files that have already been linked. 


initialized section: A COFF section that contains executable code or 
initialized data. An initialized section can be built up with the .data, .text, 
or .sect directive. 


input section: A section from an object file that will be linked into an 
executable module. 


label: A symbol that begins in column 1 of a source statement and corre- 
sponds to the address of that statement. 


line number entry: An entry in a COFF output module that maps lines of 
assembly code back to the original C source file that created them. 


linker: A software tool that combines object files to form an object module 
that can be allocated into system memory and executed by the device. 


listing file: An output file created by the assembler that lists source state- 
ments, their line numbers, and their effects on the SPC. 


load address: The address that a section loads at. 


loader: A device that loads an executable module into system memory. 


macro: A user-defined routine that can be used as an instruction. 
macro call: The process of invoking a macro. 


macro definition: A block of source statements that define the name and 
the code that make up a macro. 


macro expansion: The source statements that are substituted for the 
macro call and are subsequently assembled. 


Glossary 


macro library: An archive library composed of macros. Each file in the 
library must contain one macro; its name must be the same as the macro 
name it defines, and it must have an extension of .asm. 


magic number: A COFF file header entry that identifies an object file as a 
module that can be executed by the TMS320C3x/C4x. 


map file: An output file, created by the linker, that shows the memory 
configuration, section composition, and section allocation, as well as 
symbols and the addresses at which they were defined. 


member: The elements or variables of a structure, union, archive, or enu- 
meration. 


memory map: A map of target system memory space, which is partitioned 
into functional blocks. 


mnemonic:  Aninstructionname thatthe assembler translates into machine 
code. 


model statement: Instructions or assembler directives in a macro definition 
that are assembled each time a macro is invoked. 


named section: An initialized section that is defined with a .sect directive. 


object file: A file that has been assembled or linked and contains machine- 
language object code. 


object format converter: A program that converts COFF object files into 
Intel-format or Tektronix-format object files. 


object library: An archive library made up of individual object files. 


operand: The arguments, or parameters, of an assembly language 
instruction, assembler directive, or macro directive. 


optional header: A portion of a COFF object file that the linker uses to 
perform relocation at download time. 


options: Command parameters that allow you to request additional or 
specific functions when you invoke a software tool. 


output module: A linked, executable object file that can be downloaded 
and executed on a target system. 
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overlay page: A section of physical memory that is mapped into the same 
address range as another section of memory. A hardware switch deter- 
mines which range is active. 


partial linking: The linking of a file that will be linked again. 


RAM model: An autoinitialization model used by the linker when linking C 
code. The linker uses this model when you invoke the linker with the -cr 
option. The RAM model allows variables to be initialized at load time in- 
stead of runtime. 


raw data: Executable code or initialized data in an output section. 


relocation: Aprocess in which the linker adjusts all the references to a sym- 
bol when the symbol’s address changes. 


ROM model: An autoinitialization model used by the linker when linking C 
code. The linker uses this model when you invoke the linker with the -c 
option. In the ROM model, the linker loads the .cinit section of data tables 
into memory, and variables are initialized at runtime. 


run address: The address that a section runs at. 


section: A relocatable block of code or data that will ultimately occupy con- 
tiguous space in the TMS320C3x/C4x memory map. 


section header: A portion of a COFF object file that contains information 
about a section in the file. Each section has its own header; the header 
points to the section’s starting address, contains the section’s size, etc. 


section program counter: See SPC. 
sign-extend: To fill the unused MSBs of a value with the value’s sign bit. 


simulator: A software development system that — simulates 
TMS320C3x/C4x operation. 


source file: A file that contains C code or assembly language code that will 
be compiled or assembled to form an object file. 
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SPC: An element of the assembler that keeps track of the current location 
within a section; each section has its own SPC. 


static: Akindofvariable whose scope is confined to a function or a program. 
The values of static variables are not discarded when the function or pro- 
gram is exited; their previous value is resumed when the function or pro- 
gram is re-entered. 


storage class: Any entry in the symbol table that indicates how a symbol 
should be accessed. 


stringtable: A table that stores symbol names that are longer than 8 charac- 
ters (symbol names of 8 characters or longer cannot be stored in the 
symbol table; instead, they are stored in the string table). The name por- 
tion of the symbol’s entry points to the location of the string in the string 
table. 


structure: A collection of one or more variables grouped together under a 
single name. 


symbol: A string of alphanumeric characters that represents an address or 
a value. 


symbolic debugging: The ability of a software tool to retain symbolic infor- 
mation so that it can be used by a debugging tool such as a simulator or 
an emulator. 


symbol table: A portion of a COFF object file that contains information 
about the symbols that are defined and used by the file. 


tag: An optional “type” name that can be assigned to a structure, union, or 
enumeration. 


target memory: Physical memory in a system into which executable object 
code is loaded. 


text: One of the default COFF sections. The .text section is an initialized 
section that contains executable code. You can use the .text directive to 
assemble code into the .text section. 


unconfigured memory: Memory that is not defined as part of the 
TMS320C3x/C4x memory map and cannot be loaded with code or data. 
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uninitialized section: A COFF section that reserves space in the 
TMS320C3x/C4x memory map but that has no actual contents. These 
sections are built up with the .oss and .usect directives. 


union: A variable that may hold (at different times) objects of different types 
and sizes. 


UNION: Allocating multiple sections to run at the same address. 


unsigned: A kind of value that is treated as a positive number, regardless 
of its actual sign. 


well-defined expression: An expression that contains only symbols or as- 
sembly-time constants that have been defined before they appear in the 
expression. 


word: A 16-bit addressable location in target memory. 
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